Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
WebService::GData::CliUseroContributed Perl DWebService::GData::ClientLogin(3)

NAME
       WebService::GData::ClientLogin -	implements ClientLogin authorization
       for google data related APIs v2.

SYNOPSIS
	   #you	will want to use a service instead such	as WebService::GData::YouTube;
	   use WebService::GData::Base;
	   use WebService::GData::ClientLogin;

	   #create an object that only has read	access
	   my $base = new WebService::GData::Base();

	   my $auth;

	   eval	{
	       $auth = new WebService::GData::ClientLogin(
		   email    => '...',
		   password => '...',
		   service  => '...', #default to youtube,
		   source   => '...' #default to WebService::GData::ClientLogin-$VERSION,
		   type	   => '...'  #default to HOSTED_OR_GOOGLE
	       );
	   };
	   if(my $error	= $@){
	       #$error->code,$error->content...
	   }

	   if($auth->captcha_url){
	       #display	the image and get the answer from the user
	       #then try to login again
	   }

	   #everything is fine...
	   #give write access to the above user...

	   $base->auth($auth);

	   #now	you can... (url	are here for examples!)

	   #create a new entry with application/x-www-form-urlencoded content-type

	   my $ret = $base->post('http://gdata.youtube.com/feeds/api/users/default/playlists',$content);

	   #if it fails	a first	time, you will need to add captcha related parameters:
	   my $auth;
	   eval	{
	       $auth = new WebService::GData::ClientLogin(
		   email	  => '...',
		   password	  => '...',
		   captcha_token  => '...',
		   captcha_answer => '...'
	       );
	   };

	   #youtube specific developer key
	   my $auth;
	   eval	{
	       $auth = new WebService::GData::ClientLogin(
		    email    =>	'...',
		    password =>	'...',
		     key      => '...',
	       );
	   };

DESCRIPTION
       inherits	from WebService::GData

       Google services supports	different authorization	systems	allowing you
       to write	data programmaticly. ClientLogin is one	of such	system.	 This
       package tries to	get an authorization key to the	service	specified by
       logging in with the user	account	information: email and password.  If
       the loggin succeeds, the	authorization key generated grants you access
       to write	actions	as long	as you pass the	key with each requests.

       ClientLogin authorization key does expire but the expire	time is	set on
       a per service basis.  You should	use this authorization system for
       installed applications.	Web application	should use the OAuth (to be
       implemented) or AuthSub (will be	deprecated and will not	be
       implemented) authorization systems.

       The connection is done via ssl, therefore you should install
       Crypt::SSLeay before using this module or an error code:
       'missing_ssl_module' will be thrown.

       More information	about ClientLogin can be found here:

       <http://code.google.com/intl/en/apis/accounts/docs/AuthForInstalledApps.html>

       Some problems can be encountered	if your	account	is not directly	linked
       to a Google Account.

       Please see <http://apiblog.youtube.com/2011/03/clientlogin-fail.html>.

   CONSTRUCTOR
       new

	   Create an instance by passing an hash.

	   Parameters

	   "settings:Hash" an hash containing the following keys:(* parameters
	   are optional)
	       email
		   Specify the user email account.

	       password
		   Specifies the user password account.

	       service (default	to youtube)
		   Specify the service you want	to log in. youtube for
		   youtube, cl for calendar,etc.

		   List	available
		   here:<http://code.google.com/intl/en/apis/base/faq_gdata.html#clientlogin>.

		   Constants available in WebService::GData::Constants

	       source (default to WebService::GData::ClientLogin-$VERSION)
		   Specify the name of your application	in the following
		   format "company_name-application_name-version_id".  You
		   should provide a real source	to avoid getting blocked
		   because Google thought you are a bot...

	       type* (default to HOSTED_OR_GOOGLE)
		   Specify the type of account:	GOOGLE,HOSTED or
		   HOSTED_OR_GOOGLE.

	       key*
		   The key must	be specified for YouTube service. See "key()"
		   for further information about the key.

	       captcha_token*
		   Specify the captcha_token you received in response to a
		   failure to log in.

	       captcha_answer*
		   Specify the answer of the user for the CAPTCHA.

	   Returns

	   WebService::GData::ClientLogin

	   Throws

	   WebService::GData::Error
	       If the email or password	is not set it will throw an error with
	       invalid_parameters code.	 Other errors might happen while
	       trying to connect to the	service. You should look at the	error
	       code and	content.

	       See also
	       <http://code.google.com/intl/en/apis/accounts/docs/AuthForInstalledApps.html#Errors>
	       for error code list.

	       You can use WebService::GData::Constants	to check the error
	       code.

	   Example:

	       use WebService::GData::Base;
	       use WebService::GData::ClientLogin;

	       my $auth	= new WebService::GData::ClientLogin(
		   email	  => '...',
		   password	  => '...',
		   captcha_token  => '...',
		   captcha_answer => '...'
	       );

	       my $base	= new WebService::GData::YouTube(auth=>$auth);

   CONSTRUCTOR GETTER METHODS
       All these methods allows	you to get access to the data you passed to
       the constructor or to the data you got back from	the server.

       email

	   Get the email address set to	log in.

	   Parameters

	   "none"

	   Returns

	   "email:Scalar"

	   Example:

	       use WebService::GData::ClientLogin;

	       my $auth	= new WebService::GData::ClientLogin(
		   email	  => '...',
		   password	  => '...'
	       );

	       $auth->email;

       password

	   Get the password set	to log in.

	   Parameters

	   "none"

	   Returns

	   "password:Scalar"

	   Example:

	       use WebService::GData::ClientLogin;

	       my $auth	= new WebService::GData::ClientLogin(
		   email	  => '...',
		   password	  => '...'
	       );

	       $auth->password;

       source

	   Get the source set to log in.

	   Parameters

	   "none"

	   Returns

	   "source:Scalar"

	   Example:

	       use WebService::GData::ClientLogin;

	       my $auth	= new WebService::GData::ClientLogin(
		   email	  => '...',
		   password	  => '...'
	       );

	       $auth->source;#by default WebService::GData::ClientLogin-$VERSION

       service

	   Get the service set to log in.

	   Parameters

	   "none"

	   Returns

	   "service:Scalar"

	   Example:

	       use WebService::GData::ClientLogin;

	       my $auth	= new WebService::GData::ClientLogin(
		   email	  => '...',
		   password	  => '...'
	       );

	       $auth->service;#by default youtube

       type

	   Get the account type	set to log in.

	   Parameters

	   "none"

	   Returns

	   "account_type:Scalar"

	   Example:

	       use WebService::GData::ClientLogin;

	       my $auth	= new WebService::GData::ClientLogin(
		   email	  => '...',
		   password	  => '...'
	       );

	       $auth->service;#by default HOSTED_OR_GOOGLE

       key

	   The key is required by the youtube service to identify the
	   application making the request.  You	must handle this in the
	   developer
	   dashboard:<http://code.google.com/apis/youtube/dashboard/>.

	   See also
	   <http://code.google.com/intl/en/apis/youtube/2.0/developers_guide_protocol.html#Developer_Key>.

	   Parameters

	   "none"

	   Returns

	   "key:Scalar"

	   Example:

	       use WebService::GData::ClientLogin;

	       my $auth	= new WebService::GData::ClientLogin(
		   email	  => '...',
		   password	  => '...',
		   key		  => '...'
	       );

	       $auth->key;

   CAPTCHA GETTER METHODS
       The following getters are used in case of failure to connect leading in
       an error	response from the service requiring to proove that you are a
       human (or at least seem to...).	The reason for this error to arrive
       could be	several	errors to log in in a short interval of	time.

       captcha_token

	   Get the captcha token sent back by the server after a failure to
	   connect leading to a	CaptchaRequired	error message.

	   Parameters

	   "none"

	   Returns

	   "captcha_token:Scalar"

	   Example:

	       use WebService::GData::ClientLogin;

	       my $auth	= new WebService::GData::ClientLogin(
		   email	  => '...',
		   password	  => '...'
	       );

	       $auth->captcha_token;#by	default	nothing, so if you have	something, you did not succeed in logging in.

       captcha_url

	   Get the captcha token sent back by the server after a failure to
	   connect leading to a	CaptchaRequired	error message.	This url links
	   to an image containing the challenge.

	   Parameters

	   "none"

	   Returns

	   "captcha_url:Scalar"

	   Example:

	       use WebService::GData::ClientLogin;

	       my $auth	= new WebService::GData::ClientLogin(
		   email	  => '...',
		   password	  => '...',
	       );

	       my $url = $auth->captcha_url;#by	default	nothing, so if you have	something, you did not succeed in logging in.

	       #you could do:

	       print qq[<img src="$url"/>]; #display a	message	to decrypt...

       captcha_answer

	   Get the answer from the user	after he/she was presented with	the
	   captcha image (link in captcha_url).	 You set this parameter	in the
	   constructor.

	   Parameters

	   "none"

	   Returns

	   "captcha_answer:Scalar"

	   Example:

	       use WebService::GData::ClientLogin;

	       my $auth	= new WebService::GData::ClientLogin(
		   email	  => '...',
		   password	  => '...'
	       );

	       my $url = $auth->captcha_url;#by	default	nothing, so if you have	something, you did not succeed in logging in.

	       #you could do:

	       print qq[<img src="$url"/>]; #display a	message	to decrypt...
	       print q[<input type="text" name="captcha_answer"	value=""/>];#let the user enters the message displayed

       authorization_key

	   Get the authorization key sent back by the server in	case of
	   success to log in.  This will be the	key you	 put in	the
	   Authorization header	to each	protect	content	that you want to
	   request.  This is handled by	each service and should	be transparent
	   to the end user of the library.

	   Parameters

	   "none"

	   Returns

	   "authorization_key:Scalar"

	   Example:

	       use WebService::GData::ClientLogin;

	       my $auth	= new WebService::GData::ClientLogin(
		   email	  => '...',
		   password	  => '...'
	       );

	       my $url = $auth->authorization_key;#by default nothing, so if you have something, you did succeed in logging in.

HANDLING ERROR/CAPTCHA
       Google data APIs	relies on querying remote urls on particular services.
       All queries that	fail will throw	(die) a	WebService::GData::Error
       object.	The error instance will	contain	the error code as a string in
       code() and the full error string	in "content()".

       The CaptchaRequired code	return by the service does not throw an	error
       though as you can recover by a captcha.

       Below is	an example of how to implement the logic for a captcha in a
       web context.

       (WARNING:shall not be used in a web context though but easy to grasp!)

       Example:

	   use WebService::GData::Constants qw(:errors);
	   use WebService::GData::ClientLogin;

	   my $auth;
	   eval	{
	       $auth   = new WebService::GData::ClientLogin(
		   email => '...',#from	the user
		   password =>'...',#from the user
		   service =>'youtube',
		   source =>'MyCompany-MyApp-2'
	       );
	   };

	   if(my $error	= $@) {
	       #something went wrong, display some info	to the user
	       #$error->code,$error->content
	       if($error->code eq BAD_AUTHENTICATION){
		   #display a message to the user...
	       }
	   }

	   #else it seems ok but...

	   #check to see if got	back a captcha_url

	   if($auth->captcha_url){

	       #ok, so there was something wrong, we'll	try again.

	       my $img = $auth->captcha_url;
	       my $key = $auth->captcha_token;

	       #here an	html form as an	example
	       #(WARNING:shall not be used in a	web context but	easy to	grasp!)

	       print q[<form action="/cgi-bin/...mycaptcha.cgi"	method="POST">];
	       print qq[<input type="hidden" value="$key" name="captcha_token"/>];
	       print qq[<input type="text" value="" name="email"/>];
	       print qq[<input type="text" value="" name="password"/>];
	       print qq[<img src="$img"	/>];
	       print qq[<input type="text" value=""  name="captcha_answer"/>];

	       #submit button here
	   }

	   #once the form is submitted,	in your	mycaptcha.cgi program:

	   my $auth;
	   eval	{
	       $auth   = new WebService::GData::ClientLogin(
		   email => '...',#from	the user
		   password =>'...',#from the user
		   service =>'youtube',
		   source =>'MyCompany-MyApp-2',
		   captcha_token => '...',#from	the above form
		   captcha_answer => '...'#from	the user
	       );
	   };

	   ##error checking again:lather,rinse,repeat...

DEPENDENCIES
       LWP

       Crypt::SSLeay

BUGS AND LIMITATIONS
       If you do me the	favor to _use_ this module and find a bug, please
       email me	i will try to do my best to fix	it (patches welcome)!

AUTHOR
       shiriru <shirirulestheworld[arobas]gmail.com>

LICENSE	AND COPYRIGHT
       This library is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.

POD ERRORS
       Hey! The	above document had some	coding errors, which are explained
       below:

       Around line 225:
	   Unterminated	I<...> sequence

perl v5.32.1			  2011-05-03 WebService::GData::ClientLogin(3)

NAME | SYNOPSIS | DESCRIPTION | HANDLING ERROR/CAPTCHA | DEPENDENCIES | BUGS AND LIMITATIONS | AUTHOR | LICENSE AND COPYRIGHT | POD ERRORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=WebService::GData::ClientLogin&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help