Create an instance.

Parameters

"auth:AuthObject" (optional) - You can set an authorization object like WebService::GData::ClientLogin

Returns

WebService::GData::Base

Example:

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

Set/get an auth object that handles access to protected contents. The auth object will be used by post/insert/update/delete methods by calling two methods:

• "set_authorization_headers(base:WebService::GData::Base,req:HTTP::Request)"

  - Headers required by the authentication protocol.

• "set_service_headers(base:WebService::GData::Base,req:HTTP::Request)"

  - Extra headers required by a particular service.

• "source()"

  - The name of the application. Will be used for the user agent string.

These methods will receive the instance calling them and the request instance. They shall add any extra headers required to implement their own authentication protocol (ie,ClientLogin,OAuth,SubAuth). If the object can not handle the above methods it will not be set.

Parameters

"none" - use as a getter

"auth:Object" - use as a setter: a auth object defining the necessary methods.

Returns

"auth:Object" in a setter/getter context.

Example:

    use WebService::GData::Base;
        
    #should be in a eval {... }; block to catch an error...
        
    my $auth = new WebService::GData::ClientLogin(email=>...);

    my $base = new WebService::GData::Base(auth=>$auth);
        
    #or
        
    my $base   = new WebService::GData::Base(); 
       $base  -> auth($auth);

Set/get a query object that handles the creation of the query string. The query object will be used to add extra query parameters when calling WebService::GData::Base::get().

The query object should only implement the following methods (do not need to inherit from WebService::GData::Query):

• "get('value-name')" - Gives access to a parameter value
• "to_query_string()" - return the query string.
• "get('v')" - should return a version number >=WebService::GData::Constants::GDATA_MINIMUM_VERSION

Parameters

"none" - use as a getter

"query:Object" - use as a setter: a query object defining the necessary methods.

Returns

"query:Object" in a setter/getter context.

The WebService::GData::Query returns by default:

    '?alt=json&prettyprint=false&strict=true&v=2'

when "to_query_string()" is called.

When you call WebService::GData::Base::get(), you should only set an url with no query string:

Example:

    use WebService::GData::Constants qw(:all);
    use WebService::GData::Base;
        
    #should be in a eval { ... }; block...
    my $auth   = new WebService::GData::ClientLogin(email=>...);

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

    $base->query->alt(JSONC);
    
    $base->get('http://gdata.youtube.com/feeds/api/standardfeeds/top_rated');
    #is in fact calling:
    #http://gdata.youtube.com/feeds/api/standardfeeds/top_rated?alt=jsonc&prettyprint=false&strict=true&v=2

    #or set a new query object:
    $base->query(new WebService::GData::YouTube::Query());

Set/get the override method.

Depending on your server configurations, you might not be able to set the method to PUT/DELETE/PATCH. This will forbid you to do any updates or deletes. In such a case, you should set override_method to TRUE so that it uses the POST method but override it by the proper value (ie,PUT/DELETE/PATCH) using X-HTTP-Method-Override.

Parameters

"none" - use as a getter

"true_or_false:Scalar" - use as a setter: WebService::GData::Constants::TRUE or WebService::GData::Constants::FALSE (default)

Returns

"void" in a setter context.

"override_state:Scalar" in a getter context, either WebService::GData::Constants::TRUE or WebService::GData::Constants::FALSE.

Example:

    use WebService::GData::Constants qw(:all);
    use WebService::GData::Base;
        
        
    #using override_method makes sense only if you are logged in
    #and want to do some write methods.

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

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

    $base->override_method(TRUE);
        
    $base->update($url,$content);

Set/get the compression mode.

Depending on your perl configuration, you might be able to handle data compress using gzip. By setting this method to TRUE, the data coming from Google servers will be gzipped and unzipped for you as a convenience. It may offer a way to limit the number of bytes exchanged over the network but requires more calculation on your side. By default, compression mode is not enabled.

Parameters

"none" - use as a getter

"true_or_false:Scalar" - use as a setter: WebService::GData::Constants::TRUE or WebService::GData::Constants::FALSE (default)

Returns

"void" in a setter context.

"compression_state:Scalar" in a getter context, either WebService::GData::Constants::TRUE or WebService::GData::Constants::FALSE.

Example:

    use WebService::GData::Constants qw(:all);
    use WebService::GData::Base;
        my $base = new WebService::GData::Base();
       $base->enable_compression(TRUE);
    
    my $ret = $base->get($url);#the data was gzipped and ungzipped if possible

Get the last queried uri.

Parameters

"none" - getter only

Returns

"uri:Scalar" in a getter context, either undef if no query has been made or the uri with no query string as a Scalar.

Example:

    use WebService::GData::Base;
        
    my $base = new WebService::GData::Base();

    $base->get('http://www.example.com?v=2');
        
    $base->get_uri();#'http://www.example.com'

Set or get the user agent name set.

Parameters

"none" - getter

"name:Scalar" - set the user agent name

Returns

"user_agent_name:Scalar" the full user agent name when used in a getter context

Example:

    use WebService::GData::Base;
        
    my $base = new WebService::GData::Base();

    $base->get('http://www.example.com?v=2');
        
    $base->user_agent_name();#WebService::GData::Base/2
        
    $base->auth($auth);#where $auth->source eq 'MyApp-MyCompany-ID'

    $base->user_agent_name();#MyApp-MyCompany-ID WebService::GData::Base/2
    
    $base->user_agent_name("my app");#MyApp-MyCompany-ID my app WebService::GData::Base/2

Get the content of a feed in any format. If the format is json or jsonc, it will send back a perl object. If an auth object is specified, it will call the required methods to set the authentication headers. It will also set the 'GData-Version' header by calling $this->query->get('v'); You should put the code in a eval { ... }; block to catch any error.

Parameters

"url:Scalar" - an url to fetch that do not contain any query string.

Query string will be removed before sending the request.

Returns

"response:Object|Scalar" - a perl object if it is a json or jsonc request else the raw content.

Throws

WebService::GData::Error if it fails to reach the contents.

Example:

    use WebService::GData::Base;
        
    my $base   = new WebService::GData::Base();
    
    $base->get('http://gdata.youtube.com/feeds/api/standardfeeds/top_rated');
        
    #is in fact calling:
    #http://gdata.youtube.com/feeds/api/standardfeeds/top_rated?alt=json&prettyprint=false&strict=true&v=2

    #the query string will be erased and change to query->to_query_string()
        
    $base->get('http://gdata.youtube.com/feeds/api/standardfeeds/top_rated?alt=atom');
        
    #is in fact calling:
    #http://gdata.youtube.com/feeds/api/standardfeeds/top_rated?alt=json&prettyprint=false&strict=true&v=2

Post data to an url with application/x-www-form-urlencoded content type. An auth object must be specified. it will call the required methods to set the authentication headers.

Parameters

"url:Scalar" - the url to query

"content:Scalar|Binary" - the content to post

Returns

"response:Scalar" - the response to the query in case of success.

Throws

WebService::GData::Error if it fails to reach the contents.

Example:

    use WebService::GData::Base;
        
    #you must be authorized to do any write actions.
    my $base   = new WebService::GData::Base(auth=>...);
    
    #create a new entry with application/x-www-form-urlencoded content-type
    my $ret = $base->post($url,$content);

Insert data to an url with application/atom+xml; charset=UTF-8 content type (POST). An auth object must be specified. it will call the required methods to set the authentication headers.

Parameters

"url:Scalar" - the url to query

"content:Scalar" - the content to post

Returns

"response:Scalar" - the response to the query in case of success.

Throws

WebService::GData::Error if it fails to reach the contents.

Example:

    use WebService::GData::Base;
        
    #you must be authorized to do any write actions.
    my $base   = new WebService::GData::Base(auth=>...);
    
    #create a new entry with application/atom+xml; charset=UTF-8 content-type
    my $ret = $base->insert($url,$content);

Update data to an url with application/atom+xml; charset=UTF-8 content type (PUT). An auth object must be specified. it will call the required methods to set the authentication headers.

Parameters

"url:Scalar" - the url to query

"content:Scalar" - the content to put.

Returns

"response:Scalar" - the response to the query in case of success.

Throws

WebService::GData::Error if it fails to reach the contents.

Example:

    use WebService::GData::Base;
        
    #you must be authorized to do any write actions.
    my $base   = new WebService::GData::Base(auth=>...);
    
    #create a new entry with application/atom+xml; charset=UTF-8 content-type
    my $ret = $base->upate($url,$content);

Delete data from an url with application/atom+xml; charset=UTF-8 content type (DELETE).

Parameters

"url:Scalar" - the url to query

Returns

"response:Scalar" - the response to the query in case of success.

Throws

WebService::GData::Error if it fails to reach the contents.

Example:

    use WebService::GData::Base;
        
    #you must be authorized to do any write actions.
    my $base   = new WebService::GData::Base(auth=>...);
    
    #create a new entry with application/atom+xml; charset=UTF-8 content-type
    my $ret = $base->delete($url);