# Gallery Remote Protocol version 1

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.

- Summary
- Requests
- Commands
  1. `login` command
  2. `fetch-albums` command
  3. `add-item` command

## Summary

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.

## Requests

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.

## Notes

The results sections below assume a HTTP `200 OK` status code was returned, although a `4xx` or `5xx` result is possible. Additionally, if the protocol version is not correct, regardless of the command, an English textual error message is returned, with no other results.

## Commands

Note:The word "protocol" is misspelled in the "`protocal_version`" key.

1. ### `login` command

   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.

   - #### Context

     A request with the `login` command may be made at any time -- there are no prerequisites.

   - #### Form Data

     `cmd=login
     protocal_version=1
     uname=`gallery user name`
     password=`cleartext password

   - #### Results

     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.

2. ### `fetch-albums` command

   The `fetch-albums` command asks the server to return a list of all albums (visible with the client's logged in user permissions).

   - #### Context

     A request with the `login` command must be made before the `fetch-albums` command is used.

   - #### Form Data

     `cmd=fetch-albums
     protocal_version=1`

   - #### Results

     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.

3. ### `add-item` command

   This command asks the server to add a photo to a specified album.

   - #### Context

     A request with the `login` command must be made before the `add-item` command is used.

   - #### Form Data

     `cmd=add-item
     protocal_version=1
     set_albumName=`album name`
     userfile=`form-data-encoded image data

   - #### Results

     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.