Tim Miller <tim_miller at users dot sourceforge dot net>
This document describes the gallery remote application protocol, which is layered over HTTP, as of version 1.3.1 of gallery.
Gallery remote queries and sends information from a gallery installation through a protcol based on HTTP and form-data. The protocol leverages the same user authentication (and session cookies) as the web/HTML interface to the site. It is implemented in one PHP source file, gallery_remote.php.
Every query from client to server corresponds to one action. Multiple actions require multiple HTTP requests.
The protocol is stateful; the client must acquire the gallery session cookie by performing a login request before any other requests will succeed.
Permissions for actions performed by gallery_remote.php are controlled in the same way they are controlled for regular web/HTML users. init.php is called at the top of each request.
Each request is expressed through an HTTP POST -- parameters are expressed as HTTP form data (control-name/current value) pairs (we'll call them "key" and "value").
Each request specifies a command (the "cmd" key). Depending on which command is specified, other parameters are required in the form-data set.
Each request also specifies a protocol version (the "protocal_version" [sic] key). If the protocol version specified by the client does not match exactly $gallery->remote_protocol_version, the request is declined. The current protocol version is "1" (it has never been changed).
Each command is described below. After a brief description of the command, template form data appears and the result format (if any) is described.
Note:The word "protocol" is misspelled in the "protocal_version" key.
This command ensures a session cookie has been given to the client and, if the account information is correct, adds the proper user object to the session.
A request with the login command may be made at any time -- there are no prerequisites.
cmd=login
protocal_version=1
uname=gallery user name
password=cleartext password
If the login succeeds, the value
SUCCESS
is returned. If the login fails, the value
Login Incorrect
is returned. If either the uname or password keys are missing, the value
Missing Parameters
is returned.
The fetch-albums command asks the server to return a list of all albums (visible with the client's logged in user permissions).
A request with the login command must be made before the fetch-albums command is used.
cmd=fetch-albums
protocal_version=1
If successful, the a request using the fetch-albums command returns tab- and newline-delimited data. Each line consists of an album name, a tab character, the album title and a newline, except the last line which will contain the value
SUCCESS
If the "SUCCESS" value is not present, the list of albums should not be considered complete and the request to have failed.
This command asks the server to add a photo to a specified album.
A request with the login command must be made before the add-item command is used.
cmd=add-item
protocal_version=1
set_albumName=album name
userfile=form-data-encoded image data
If the file upload succeeds the value
SUCCESS
is returned. If the file upload fails, a line beginning with the value
ERROR:
and followed by an English-language description of the reason is returned.