/ 
Net-API-Gett-0.02
River stage zero No dependents
/ Net::API::Gett

NAME

Net::API::Gett - Perl bindings for Ge.tt API

VERSION

Version 0.02

SYNOPSIS

use v5.10;
use Net::API::Gett;

# Get API Key from http://ge.tt/developers

my $gett = Net::API::Gett->new( 
    api_key      => 'GettAPIKey',
    email        => 'me@example.com',
    password     => 'mysecret',
);

my $file_obj = $gett->upload_file( 
    filename => "ossm.txt",
    contents => "/some/path/example.txt",
       title => "My Awesome File", 
    encoding => ":encoding(UTF-8)" 
);

say "File has been shared at " . $file_obj->url;

my $file_contents = $gett->get_file_contents( $file_obj->sharename, 
        $file_obj->fileid );

open my $fh, ">:encoding(UTF-8)", "/some/path/example-copy.txt" 
    or die $!;
print $fh $file_contents;
close $fh;

# clean up share and file(s)
$gett->destroy_share($file_obj->sharename);

ABOUT

Gett is a clutter-free file sharing service that allows its users to share up to 2 GB of files for free. They recently implemented a REST API; this is a binding for the API. See http://ge.tt/developers for full details and how to get an API key.

ATTRIBUTES

api_key

Scalar string. Read-only. has_api_key predicate.

email

Scalar string. Read-only. has_email predicate.

password

Scalar string. Read-only. has_password predicate.

access_token

Scalar string. Populated by login call. has_access_token() predicate.

access_token_expiration

Scalar integer. Unix epoch seconds until an access token is no longer valid which is currently 24 hours (86400 seconds.) This value is suitable for use in a call to localtime().

refresh_token

Scalar string. Populated by login call. Can be used to generate a new valid access token without reusing an email/password login method. has_refresh_token() predicate.

base_url

Scalar string. Read-only. Populated at object construction. Default value: https://open.ge.tt/1.

ua

LWP::UserAgent object. Read only. Populated at object construction. Uses a default LWP::UserAgent if not supplied.

user

Net::API::Gett::User object. Populated by login and/or my_user_data. has_user() predicate.

METHODS

Unless otherwise noted, these methods die if an error occurs or if they get a response from the API which is not successful. If you need to handle errors more gracefully, use Try::Tiny to catch fatal errors.

new()

This method instantiates a new object. One of the following parameter argument lists is required at construction time:

  • a valid refresh token,

  • a valid access token, or,

  • a valid api key, email and password

One of these three is required to pass in the access token parameter to the Gett API when it is required. (If an access token is not specified, the API will automatically attempt to log in and get one lazily.)

Account methods

login()

This method populates the access_token, refresh_token and user attributes. It usually doesn't need to be explicitly called since methods which require an access token will automatically (and lazily) attempt to log in to the API and get one.

Returns a perl hash representation of the JSON output for https://open.ge.tt/1/users/login.

my_user_data()

Retrieves (and/or refreshes) user data held in the user attribute. This method returns a Net::API::Gett::User object.

Share functions

All of these functions cache Net::API::Gett::Share objects in the shares attribute. The cache is updated whenever calls return successfully from the API so the local cache will be in sync with remote information about a given share as long as no changes were made to a share outside of this library.

get_shares()

Retrieves all share information for the given user. Takes optional scalar integers offset and limit parameters, respectively.

Returns a list of Net::API::Gett::Share objects.

get_share()

Retrieves (and/or refreshes cached) information about a specific single share. Requires a sharename parameter.

Returns a Net::API::Gett::Share object.

create_share()

This method creates a new share instance to hold files. Takes an optional string scalar parameter which sets the share's title attribute.

Returns the new share as a Net::API::Gett::Share object.

update_share()

This method updates share attributes. At present, only the share title can be changed (or deleted), so pass in a string to set a new title for a specific share.

Calling this method with an empty parameter list or explicitly passing undef will delete any title currently set on the share.

Returns a Net::API::Gett:Share object with updated values.

destroy_share()

This method destroys the specified share and all of that share's files. Returns a true boolean on success.

File functions

get_file()

Returns a Net::API::Gett::File object given a sharename and a fileid.

upload_file()

This method uploads a file to Gett. The following key/value pairs are valid:

  • sharename (optional)

    If not specified, a new share will be automatically created.

  • title (optional)

    If specified, this value is used when creating a new share to hold the file.

  • filename (required)

    What to call the uploaded file when it's inside of the Gett service.

  • content (optional)

    A representation of the file's contents. This can be one of:

    A buffer
    An IO::Handle object
    A FILEGLOB
    A pathname to a file to be read

    If not specified, the filename parameter is used as a pathname.

  • encoding

    An encoding scheme for the file content. By default it uses :raw

Returns a Net::API::Gett:File object representing the uploaded file.

send_file()

This method actually uploads the file to the Gett service. This method is normally invoked by the upload_file() method, but it's a public method which might be useful in combination with get_new_upload_url(). It takes the following parameters:

  • a PUT based Gett upload url

  • a scalar representing the file contents which can be one of: a buffer, an IO::Handle object, a FILEGLOB, or a file pathname.

  • an encoding scheme. By default, it uses :raw (see perldoc -f binmode for more information.)

Returns a true value on success.

get_new_upload_url()

This method returns a scalar PUT upload URL for the specified sharename/fileid parameters. Potentially useful in combination with send_file().

destroy_file()

This method destroys a file specified by the given sharename/fileid parameters. Returns a true value.

get_file_contents()

This method retrieves the contents of a file in the Gett service given by the sharename/fileid parameters. You are responsible for outputting the file (if desired) with any appropriate encoding.

get_thumbnail()

This method returns a thumbnail if the file in Gett is an image. Requires a sharename and fileid.

get_scaled_contents()

This method returns scaled image data (assuming the file in Gett is an image.) Requires sharename, fileid, width and height paramters, respectively.

add_share()

This method populates/updates the Net::API::Gett:Share object local cache.

shares()

This method retrieves one or more cached Net::API::Gett::Share objects. Objects are requested by sharename. If no parameter list is specified, all cached objects are returned in an unordered list. (The list will not be in the order shares were added to the cache.)

If no objects are cached, this method returns an empty list.

AUTHOR

Mark Allen, mrallen1 at yahoo dot com

BUGS

Please report any bugs or feature requests to bug-net-api-gett at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-API-Gett. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Net::API::Gett

You can also look for information at:

SEE ALSO

Gett API documentation

CONTRIBUTORS

Thanks to the following for patches:

LICENSE AND COPYRIGHT

Copyright 2011 Mark Allen.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.