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

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_remotemaj.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.

  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).

  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.

  4. add-item command

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

  5. album-properties command [since 2.0]

    This command asks the server for information on an album.

  6. new-album command [since 2.1]

    This command creates a new album on the server.


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 $