NAME

Gallery::Remote::API - Interact with Gallery via the Gallery Remote Protocol

VERSION

This document describes Gallery::Remote::API version 0.01.01

SYNOPSIS

use Gallery::Remote::API;

my $gallery = new Gallery::Remote::API ({
	url => $url, version => $ver, username => $user, password => $pass
});

$gallery->login || die "can't log in!";


## Then...

if (my $result = $gallery->fetch_albums) { #etc
	# success! $result is a hashref of returned data
}
else {
	# failed! But we can still get $result, to see the error
	my $result = $gallery->result;
	print "error = " . $result->{status_text};
}

DESCRIPTION

"Gallery" is a PHP web photo gallery package; this module allows you to interact with their Remote Protocol API. It is an alternative to Gallery::Remote, which does not support Gallery2.

INTERFACE - COMMON METHODS

These are the general-purpose methods you'll use to interact with this class.

`new`

my $gallery = new Gallery::Remote::API ({
	url => $url, version => $ver, username => $user, password => $pass
});

Constructs a new Gallery::Remote::API object. Arguments, which must be passed as a hashref, are as follows:

url (required)

The main url to your Gallery installation, e.g. "mygallerysite.com", or "http://mybigbadsite.com/galleries/". The 'http://' is optional. Can be passed as either a string or as a URI object.

Note that you probably can't use the url of an embedded Gallery installation, you need to use the primary installation url. At least, that's my experience with an installation embedded under Wordpress, where I have a mygallery.mywordpresssite.com primary installation embedded under a mywordpresssite.com/gallery address, the remote protocol only works under mygallery.mywordpresssite.com.

version

The (major) version of your Gallery installation. Accepted values are '1' or '2'; defaults to '2'.

username

password

The Gallery username and password under which you wish to log in

`result`

my $result = $gallery->result

Returns a hashref containing the deserialized data tree resulting from the most recently performed request. This is the same data that is returned from a successful request, but you'll need this to get the error message on a fail.

The $result data will ALWAYS contain at least the following:

{ status => $status_code, status_text => $message }

A status of '0' indicates a success, any other value is an error code. 'Proper' Remote Protocol error codes will be numeric, and the status_text will describe the error.

See http://codex.gallery2.org/Gallery_Remote:Protocol#Appendix_A for the current list of status codes.

In the event that we fail to contact the remote server at all, we provide the following, which includes the HTTP::Response object itself:

{ status => 'server_error', status_text => $http_response->message,
	response => $http_response }

All other data included in the $result is contextual to the request that was made.

`response`

my $response = $gallery->response;

Returns the raw, un-deserialized response data resulting from the most recently performed request. Data is formatted in a Java "Properties" stream, exactly as returned by the Gallery Remote Protocol.

You shouldn't normally need this, but it may be useful for debugging.

`url`

`username`

`password`

`version`

my $url = $gallery->url; #etc

Read-only accessors to retrieve the data you assigned on construction.

INTERFACE - PROTOCOL COMMAND METHODS

These are the methods which perform specific commands correlating to their similarly named equivalents as specified by the protocol.

`login`

$gallery->login
	|| die "Can't log in: " . $gallery->result->{status_text};

Logs into the Gallery installation using the username and password that were passed to the constructor. Not strictly necessary, as you may operate as a "Guest", just like on the site, but you probably can't do much in that case.

`fetch_albums`

`fetch_albums_prune`

`add_item`

`album_properties`

`new_album`

`fetch_album_images`

`move_album`

`increment_view_count`

`image_properties`

`no_op`

Each of the above executes the corresponding command against the protocol. Usage of each is identical:

#general form

my $result = $gallery->method_name(\%params) ||
	my $error_result = $gallery->result;

#example

my $result = $gallery->fetch_albums({ no_perms => 'yes' }) ||
	print "error = " . $gallery->result->{status_text} ."\n";

The parameters that can be passed to each individual method are documented in the Gallery Codex at http://codex.gallery2.org/Gallery_Remote:Protocol

In order to keep this module flexible, and reasonably backward-and-forward compatible, we do no checking whatsover on what parameters you send, we let it be between you and the remote server to determine what should or shouldn't work.

However, you do NOT need to send the cmd or protocol_version parameters, the module will handle these two for you. If you do send cmd, it will be ignored. However if you send protocol_version, your value will be used instead of the default (protocol_version = 2.9 as of this release).

I allow this because I can't find any good documentation regarding why we send that parameter, or what happens when it changes, so I'll let you overwrite it, if that helps you. If nothing else I imagine it may prove useful for forward compatibility.

Also note, you do not need to specify your Gallery2 parameters in the

g2_form[parametername]

format. Just use the parameter name itself, we will wrap it in the g2_form[].

Finally let me emphasize one point regarding parameters from Gallery's docs that bit me until I remembered:

album "names" and image "names" are actually the unique identifier (an 
integer) of the object in G2, rather than an alphanumeric name

Let me add to that: these are not the "reference numbers" which are returned by, say fetch-albums, they are the ids that those reference nums point to. So, for example, fetch-albums returns:

'album' => { 'name' => { '6' => '116' } }

'116' here is the item id which they're calling 'name', not '6'. I'm not sure where the '6' comes from, or if it's at all useful, except for referencing back to other keys in that same result hash.

`execute_command`

my $result = $gallery->execute_command($command,\%params) ||
	my $error_result = $gallery->result;

execute_command is the method which all of the above convenience methods actually call underneath. I make it public again for forward/backward compatibility -- you can use this method directly if there's an old or new command available that you need, that we haven't covered with a convenience method.

It works just like the methods above, except that you must pass the name of the command to be executed as the first argument. Use the Gallery-native form of the command, e.g. fetch-albums, not fetch_albums.

COMMAND LINE UTILITY `remotegallery`

A barebones command line utility called remotegallery is included with the distribution which will allow you to execute arbitrary commands against a Gallery server via this module. See the program's own docs at remotegallery for complete instructions, but general use is:

remotegallery --url url --version N
	--username myusername --password mypassword
	--command thecommand  --parameters param1=val1&parm2=val2...

CONFIGURATION AND ENVIRONMENT

Gallery::Remote::API requires no configuration files or environment variables.

DEPENDENCIES

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

No bugs have been reported.

Limitations: this module has been tested and runs fine against a server running Gallery Version 2.3.1, which reports server_version 2.14 (which I believe to be the same as the protocol_version? But it's the newest release and the docs say the protocol goes to 2.9? And what's up with different protocol_versions for Gallery1 vs Gallery2, do I care? Their documents are somewhat thin and frustrating. But hey, it's open source, and I'm not volunteering). So, YMMV as to whether this works for your installation, and any input to help make sure this thing works for any implementation is appreciated.

Please report any bugs or feature requests to bug-gallery-remoteapi@rt.cpan.org, or through the web interface at http://rt.cpan.org.

AUTHOR

Jonathan Wright <mysteryte@cpan.org>

Latest development version available at http://github.com/mysteryte/gallery-remote-api

LICENCE AND COPYRIGHT

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

To install Gallery::Remote::API, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Gallery::Remote::API

CPAN shell

perl -MCPAN -e shell
install Gallery::Remote::API

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

DESCRIPTION

INTERFACE - COMMON METHODS

new

result

response

url

username

password

version

INTERFACE - PROTOCOL COMMAND METHODS

login

fetch_albums

fetch_albums_prune

add_item

album_properties

new_album

fetch_album_images

move_album

increment_view_count

image_properties

no_op

execute_command

COMMAND LINE UTILITY remotegallery