Tim Miller <tim_miller
at users dot sourceforge dot net>
Pierre-Luc Paour <paour
at users dot sourceforge dot net>
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.
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.
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).
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.
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).
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.
A request with the login command may be made at any time — there are no prerequisites.
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.
#__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.
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
protocol_version=2.0
#__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
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 number of albums in the response is returned as number-of-albums.
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.
A request with the login command must be made before the fetch-albums-prune command is used.
cmd=fetch-albums-prune
protocol_version=2.2
#__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
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 number of albums in the response is returned as number-of-albums.
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
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]
#__GR2PROTO__
status=result-code
status_text=explanatory-text
If the result-code equal to GR_STAT_SUCCESS, the file upload succeeded.
This command asks the server for information on an album.
A request with the login command must be made before the album-properties command is used.
cmd=album-properties
protocol_version=2.0
set_albumName=album name
#__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.
This command creates a new album on the server.
A request with the login command must be made before the album-properties command is used.
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.
#__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.
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 $