# Gallery Remote Protocol version 2

Tim Miller <tim_miller at users dot sourceforge dot net>
Pierre-Luc Paour <paour at users dot sourceforge dot net>

## Contents

- 1. Introduction
- 2. Overview
- 3. Client-Server Interaction
- 4. Requests
- 5. Responses
- 6. Commands
  1. `login` command
  2. `fetch-albums` command
  3. `fetch-albums-prune` command
  4. `add-item` command
  5. `album-properties` command
  6. `new-album` command
- Appendix A: Response Status Codes

## 1. Introduction

This document describes version 2 of the Gallery remote application protocol, and its minor revisions.

Also see documentation of the previous version of the protocol.

The "Gallery Remote" remote administration program is this protocol's raison d'être. Version 1 of the protocol was tied very tightly to that application. It is clear that in addition to Gallery Remote users, there is a growing number of users that would like to query and control Gallery installations with their own programs.

Version 2 adds some extra features but (hopefully) greater potential for other remote applications based on Gallery. If you would like to make suggestions for future work on the Gallery Remote protocol, please submit them to either of the authors.

## 2. Overview

Gallery remote queries and sends information from a Gallery server through a protocol 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 the PHP source file `gallery_remote2.php`.

Each query from client to server corresponds to one action. Multiple actions require multiple HTTP requests.

The protocol is stateful and depends on the client supporting cookies. The client must provide login credentials for the session to be validated by sending a login request before any other requests will succeed.

Permissions for actions performed by `gallery_remote2.php` are controlled in the same way they are controlled for regular web/HTML users of Gallery. `init.php` is called before each request is processed by the server.

## 3. Client-Server Interaction

All client-server interaction follows the standard HTTP model. The client initiates all interactions with a request. The server always responds with one response. The data format of each request is HTTP form-data key/value pairs. The data format of each response is plain text key/value pairs.

Each request specifies a command value (and possibly some corresponding parameters) which determines the content of the response. Command-specific responses are defined in the context of each command below).

## 4. Requests

Each request from the client is sent to the server through an HTTP POST. Parameters of the request are expressed as HTTP form data. Form data uses a key / value format referred to in the spec as "control-name / current value." Here we simply refer to "key" and "value".

Each request must specify a command (the "`cmd`" key). Depending on which command is specified, other key/value pairs are required in the form-data set (as parameters).

Each request must specify a protocol version (the `protocol_version` key).

The server's response to the login command includes the version of the protocol it implements (with the `server_version` key). Protocol numbers obey the following convention:
maj`.`min
where maj is the major version number and min is the minor version number. Different major versions of the protocol use different `gallery_remote` maj`.php` files. Each such file may provide support for various minor versions.

Each command is described in the Commands section below. After a brief description of the command, template form data appears and the contents of the server's response is described.

## 5. Responses

After the client POSTs a request, the server sends a response to the client. The format of the response is a key/value format compatible with the Java "Properties" stream format.

In a nutshell: lines beginning with a `#` character are ignored. The text before the first `=` character is the key. The remainder of the text after the `=` until the end-of-line character(s) is the value.

Each response must begin with the text `#__GR2PROTO__`. Clients should ignore any text above this tag: it might be debug output from the server.

Each response must contain at least the keys: `status` and `status_text`.

The value associated with the `status` key is an integer status code (the codes are defined in Appendix A. For example, if the server was able to complete the command in the client's request, the value of the `status` code will be GR_STAT_SUCCESS.

The `status` key is definitive, yet the `status_text` may contain human-readable additional information (likely to be English language only).

Otherwise, if the server was not able to successfully complete the request, the status will be a non-zero integer (see Appendix A: Response Status Codes).

## 6. Commands

1. ### `login` command

   This command adds the proper user object to the session (if the username and password are correct). It also returns to the client the version of the protocol the server is prepared to support.

   - #### Context

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

   - #### Form Data

     `cmd=login
     protocol_version=2.0`
     `uname=`gallery-user-name`
     password=`cleartext-password

     where gallery-user-name is a valid gallery user name and cleartext-password is the corresponding password.

   - #### Results

     `#__GR2PROTO__`
     `status=`result-code
     `status_text=`explanatory-text
     `server_version=`major-version`.`minor-version

     If the result-code is equal to GR_STAT_SUCCESS, the login completed successfully and the user's session has been updated. Any other command can now be used in requests to this server.

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
     protocol_version=2.0`

   - #### Results

     `#__GR2PROTO__`
     `status=`result-code
     `status_text=`explanatory-text
     /`album.name.`ref-num`=`album-url-name
     |`album.title.`ref-num`=`album-display-name
     |`album.parent.`ref-num`=`parent-ref-num
     0...n |`album.perms.add.`ref-num`=`boolean
     |`album.perms.write.`ref-num`=`boolean
     |`album.perms.del_item.`ref-num`=`boolean
     |`album.perms.del_alb.`ref-num`=`boolean
     |`album.perms.create_sub.`ref-num`=`boolean
     \`album.info.extrafields.`ref-num`=`extra-fields [since 2.3]
     `album_count=`number-of-albums

     If the result-code is equal to GR_STAT_SUCCESS, the album data was fetched successfully

     If successful, a response to the `fetch-albums` command returns several keys for each album in the gallery, where

     - ref-num is a reference number,
     - album-url-name is the name of the partial URL for the gallery,
     - album-display-name is the gallery's visual name,
     - parent-ref-num refers to some other album's ref-num,
     - extra-fields is a comma-separated list of extra fields names,
     - and boolean represents a boolean value. `true` is considered true, any other value false.

     A parent-ref-num of `0` (zero) indicates that the album is a "top-level" album (it has no parent).

     Several "permissions" are reported for each album. The reported permissions are the effective permissions of the currently logged in user.

     - the add permission allows the user to add a picture to the album.
     - the write permission allows the user to add and change pictures in the album.
     - the del_item permission allows the user remove pictures from the album.
     - the del_alb permission allows the user to delete the album.
     - the create_sub permission allows the user to create nested albums in the album.

     The number of albums in the response is returned as number-of-albums.

3. ### `fetch-albums-prune` command [since 2.2]

   The `fetch-albums-prune` command asks the server to return a list of all albums that the user can either write to, or that are visible to the user and contain a sub-album that is writable (including sub-albums several times removed).
   The reason for this slightly altered version of `fetch-albums` is two-fold: the previous version was slow on the server-side, because of the way it was structured, and limitation in the Gallery mode of operation; it returns all albums the the user can read, even if writing is not allowed. This new version is faster, because it uses a more efficient algorithm to find albums; it is more efficient because it only sends albums that are useful to the client. It also doesn't parse the pictures database, which makes it run much faster on the server.

   - #### Context

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

   - #### Form Data

     `cmd=fetch-albums-prune
     protocol_version=2.2`

   - #### Results

     `#__GR2PROTO__`
     `status=`result-code
     `status_text=`explanatory-text
     /`album.name.`ref-num`=`album-url-name
     |`album.title.`ref-num`=`album-display-name
     |`album.parent.`ref-num`=`parent-name
     0...n |`album.perms.add.`ref-num`=`boolean
     |`album.perms.write.`ref-num`=`boolean
     |`album.perms.del_item.`ref-num`=`boolean
     |`album.perms.del_alb.`ref-num`=`boolean
     |`album.perms.create_sub.`ref-num`=`boolean
     \`album.info.extrafields.`ref-num`=`extra-fields [since 2.3]
     `album_count=`number-of-albums

     If the result-code is equal to GR_STAT_SUCCESS, the album data was fetched successfully

     If successful, a response to the `fetch-albums-prune` command returns several keys for each album in the gallery, where

     - ref-num is the album name (ID),
     - album-url-name is the name of the partial URL for the gallery,
     - album-display-name is the gallery's visual name,
     - parent-name refers to some other album's name,
     - extra-fields is a comma-separated list of extra fields names,
     - and boolean represents a boolean value. `true` is considered true, any other value false.

     A parent-ref-num of `0` (zero) indicates that the album is a "top-level" album (it has no parent).

     Several "permissions" are reported for each album. The reported permissions are the effective permissions of the currently logged in user.

     - the add permission allows the user to add a picture to the album.
     - the write permission allows the user to add and change pictures in the album.
     - the del_item permission allows the user remove pictures from the album.
     - the del_alb permission allows the user to delete the album.
     - the create_sub permission allows the user to create nested albums in the album.

     The number of albums in the response is returned as number-of-albums.

4. ### `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
     protocol_version=2.0
     set_albumName=`album name`
     userfile=`form-data-encoded image data
     `caption=`caption [since 2.0]
     `force_filename=`name of the file on the server [since 2.0]
     `extrafield_fieldname=`value of the extra field fieldname [since 2.3]

   - #### Results

     `#__GR2PROTO__`
     `status=`result-code
     `status_text=`explanatory-text

     If the result-code equal to GR_STAT_SUCCESS, the file upload succeeded.

5. ### `album-properties` command [since 2.0]

   This command asks the server for information on an album.

   - #### Context

     A request with the `login` command must be made before the `album-properties` command is used.

   - #### Form Data

     `cmd=album-properties
     protocol_version=2.0
     set_albumName=`album name

   - #### Results

     `#__GR2PROTO__`
     `status=`result-code
     `status_text=`explanatory-text
     `auto_resize=`resize-dimension

     If the result-code is equal to GR_STAT_SUCCESS, the request succeeded.

     If the an image uploaded with the `add-item` command's largest dimension is greater than resize-dimension, the server will resize it.

     If the value is `0` (zero), the Gallery server does not intend to resize uploaded images.

6. ### `new-album` command [since 2.1]

   This command creates a new album on the server.

   - #### Context

     A request with the `login` command must be made before the `album-properties` command is used.

   - #### Form Data

     `cmd=album-properties
     protocol_version=2.1
     set_albumName=`parent-album-name or empty to create at top level
     `newAlbumName=`album-name
     `newAlbumTitle=`album-title
     `newAlbumDesc=`album-description

     where parent-album-name is the name of the gallery that the new album should be created under;
     album-name is the new album's desired name;
     album-title is the new album's desired title;
     album-description is the new album's desired description.

     If parent-album-name is empty, the album is created at the top level.

   - #### Results

     `#__GR2PROTO__`
     `status=`result-code
     `status_text=`explanatory-text

     If the result-code is equal to GR_STAT_SUCCESS, the request succeeded.

     If the result-code is equal to GR_STAT_NO_CREATE_ALBUM_PERMISSION, the logged-in user doesn't have permission to create an album in the specified location.

## Appendix A: Response Status Codes

Status name | Code | Description
--- | --- | ---
GR_STAT_SUCCESS | 0 | The command the client sent in the request completed successfully. The data (if any) in the response should be considered valid.
GR_STAT_PROTO_MAJ_VER_INVAL | 101 | The protocol major version the client is using is not supported.
GR_STAT_PROTO_MIN_VER_INVAL | 102 | The protocol minor version the client is using is not supported.
GR_STAT_PROTO_VER_FMT_INVAL | 103 | The format of the protocol version string the client sent in the request is invalid.
GR_STAT_PROTO_VER_MISSING | 104 | The request did not contain the required `protocol_version` key.
GR_STAT_PASSWD_WRONG | 201 | The password and/or username the client send in the request is invalid.
GR_STAT_LOGIN_MISSING | 202 | The client used the login command in the request but failed to include either the username or password (or both) in the request.
GR_STAT_UNKNOWN_CMD | 301 | The value of the `cmd` key is not valid.
GR_STAT_NO_ADD_PERMISSION | 401 | The user does not have permission to add an item to the gallery.
GR_STAT_NO_FILENAME | 402 | No filename was specified.
GR_STAT_UPLOAD_PHOTO_FAIL | 403 | The file was received, but could not be processed or added to the album.
GR_STAT_NO_CREATE_ALBUM_PERMISSION | 501 | A new album could not be created because the user does not have permission to do so.
GR_STAT_CREATE_ALBUM_FAILED | 502 | A new album could not be created, for a different reason (name conflict).

`$Id: gal_remote_proto-2.html,v 1.9 2003/06/25 23:02:38 paour Exp $`