5. Gallery Remote Protocol

5.1. Introduction
5.2. G2 support
5.3. Overview
5.4. Client-server interactions
5.5. Requests
5.6. Responses
5.7. Commands
5.7.1. Login
5.7.2. Getting a list of albums
5.7.3. Getting a list of albums v2, more efficient [since 2.2]
5.7.4. Uploading a photo to an album
5.7.5. Getting information about an album [since 2.0]
5.7.6. Creating a new album [since 2.1]
5.7.7. Getting the list of photos in an album [since 2.4]
5.7.8. Moving an album [since 2.7]
5.8. Appendix A: Response Status Codes

5.1. Introduction

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

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.

5.2. G2 support

The long-term plan for G2 remote access is to design a protocol based on SOAP. However, as a stopgap, we have implemented very basic for protocol 2 in G2, with some small differences.

Only login, fetch-albums-prune and add-item are supported.

Also, because of G2-specific constraints, the format of the URLs is a bit different:

  • The base URL is http://www.example.com/g2_path/main.php

  • An additional URL parameter needs to always be added: g2_controller=remote:GalleryRemote

  • Each parameter needs to be modified to g2_form[name]=value

  • except in add-item, where userfile and userfile_name become g2_userfile and g2_userfile_name respectively.

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

5.4. Client-server interactions

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

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

5.7. Commands

5.7.1. Login

The login 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.

The login command is not strictly necessary: if it is not used, the server will assume anonymous access and the protocol will be able to access data that is accessible by anybody. In this mode, it is unlikely the new albums can be created and photos uploaded.

5.7.1.1. Context

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

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

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

5.7.2. Getting a list of albums

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

5.7.2.1. Context

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

5.7.2.2. Form data
cmd=fetch-albums
protocol_version=2.0
5.7.2.3. Results
          #__GR2PROTO__
         status=result-code
         status_text=explanatory-text
        /album.name.ref-num=album-url-name
        |album.title.ref-num=album-display-name
        |album.summary.ref-num=album-summary [since 2.8]
        |album.parent.ref-num=parent-ref-num
        |album.resize_size.ref-num=image-resize-size [since 2.8]
        |album.max_size.ref-num=image-max-size [since 2.15]
  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
       	 can_create_root=yes/no [since 2.11]

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,

  • album-summary is the summary of the album,

  • parent-ref-num refers to some other album's ref-num. A parent-ref-num of 0 (zero) indicates that the album is a "top-level" album (it has no parent).

  • image-resize-size is the intermediate size of images created when a large image is added to an album,

  • image-max-size is the maximum size of images created when a large image is added to an album,

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

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.

can_create_root will be set to either yes or no depending on the user's permissions to create albums at the root level.

5.7.3. Getting a list of albums v2, more efficient [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.

5.7.3.1. Context

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

5.7.3.2. Form data
cmd=fetch-albums-prune
protocol_version=2.2
check_writeable=yes/no [since 2.13]
5.7.3.3. Results
          #__GR2PROTO__
         status=result-code
         status_text=explanatory-text
        /album.name.ref-num=album-url-name
        |album.title.ref-num=album-display-name
        |album.summary.ref-num=album-summary [since 2.8]
        |album.parent.ref-num=parent-name
        |album.resize_size.ref-num=image-resize-size [since 2.8]
        |album.thumb_size.ref-num=image-thumb-size [since 2.9]
        |album.max_size.ref-num=image-max-size [since 2.15]
  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
	 can_create_root=yes/no [since 2.11]

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 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,

  • album-summary is the summary of the album,

  • parent-name refers to the parent album's name (this is different from the fetch-albums command. A parent-name of 0 (zero) indicates that the album is a "top-level" album (it has no parent).

  • image-resize-size is the intermediate size of images created when a large image is added to an album,

  • image-max-size is the maximum size of images created when a large image is added to an album,

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

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.

can_create_root will be set to either yes or no depending on the user's permissions to create albums at the root level.

5.7.4. Uploading a photo to an album

The add-item command asks the server to add a photo to a specified album.

5.7.4.1. Context

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

5.7.4.2. Form data
cmd=add-item
protocol_version=2.0
set_albumName=album name
userfile=form-data-encoded image data [since 2.0] or URL of image [since 2.12]
userfile_name=file name (usually inserted automatically by HTTP library, which is why we also have force_filename
caption=caption (optional) [since 2.0]
force_filename=name of the file on the server (optional) [since 2.0]
auto_rotate=yes/no (optional) [since 2.5]
extrafield.fieldname=value of the extra field fieldname (optional) [since 2.3]

Multiple extrafield lines with different fieldname values can be used.

Only gallery administrators can specify a URL as the userfile.

5.7.4.3. Results
#__GR2PROTO__
status=result-code
status_text=explanatory-text

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

5.7.5. Getting information about an album [since 2.0]

The album-properties command asks the server for information about an album.

5.7.5.1. Context

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

5.7.5.2. Form data
cmd=album-properties
protocol_version=2.0
set_albumName=album name
5.7.5.3. Results
#__GR2PROTO__
status=result-code
status_text=explanatory-text
auto_resize=resize-dimension
max_size=max-dimension [since 2.15]
add_to_beginning=yes/no

If the status is equal to GR_STAT_SUCCESS, the request succeeded.

If an image is uploaded such that its largest dimension is greater than max-dimension, the server will resize it. Otherwise, the server will use the original image that was uploaded for both the full-sized and the resized size. In all cases a thumbnail-sized image will be created. The creation of a thumbnail is highly dependant on the size of the image that was uploaded.

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

add_to_beginning will contain yes or no based on whether the album will add images to the beginning or the end of the album. [since 2.10]

5.7.6. Creating a new album [since 2.1]

The new-album command asks the server to add a new album to the gallery installation.

5.7.6.1. Context

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

5.7.6.2. Form data
cmd=new-album
protocol_version=2.1
set_albumName=parent-album-name
newAlbumName=album-name (optional)
newAlbumTitle=album-title (optional)
newAlbumDesc=album-description (optional)
  • parent-album-name is the name of the gallery that the new album should be created under, or 0 to create the album at the top-level;

  • album-name is the new album's desired name. The name must be unique within the Gallery. If it is not, then Gallery will assign an automatically-generated name. An automatically generated name will also be used if this parameter is not provided or is empty;

  • album-title is the new album's desired title;

  • album-description is the new album's desired description.

5.7.6.3. Results
#__GR2PROTO__
status=result-code
status_text=explanatory-text
album_name=actual-name [since 2.5]

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.

If an album is created with the same name as an already existing album or album-title is left blank, gallery will automatically generate an album name. actual-name will return the name of the newly created album.

5.7.7. Getting the list of photos in an album [since 2.4]

The fetch-album-images command asks the server to return information about all the images in an album. It ignores sub-albums.

5.7.7.1. Context

A request with the login command can be made before the fetch-album-images command is used, but since viewing photos in an album is generally (but not always) open to non logged-in users, a login is not always necessary.

5.7.7.2. Form data
cmd=fetch-album-images
protocol_version=2.4
set_albumName=album-name
albums_too=yes/no [since 2.13]
  • If set_albumName empty, the root albums are listed. Of course, this only works in G1 if albums_too is also used, since no pictures are in the root album. In G2, it can be used without albums_too [since 2.13]

5.7.7.3. Results
         #__GR2PROTO__
         status=result-code
         status_text=explanatory-text
        /image.name.ref_num=filename of the image
        |image.raw_width.ref_num=the width of the full-sized image
        |image.raw_height.ref_num=the height of the full-sized image
        |image.resizedName.ref_num=filename of the resized image, if there is one
        |image.resized_width.ref_num=the width of the resized image, if there is one [since 2.9]
        |image.resized_height.ref_num=the height of the resized image, if there is one [since 2.9]
        |image.thumbName.ref_num=filename of the thumbnail [since 2.9]
        |image.thumb_width.ref_num=the width of the thumbnail [since 2.9]
        |image.thumb_height.ref_num=the height of the thumbnail [since 2.9]
        |image.raw_filesize.ref_num=size of the full-sized image
        |image.caption.ref_num=caption associated with the image
  0...n |image.extrafield.fieldname.ref_num=value of the extra field of key fieldname
        |image.clicks.ref_num=number of clicks on the image
        |image.capturedate.year.ref_num=date of capture of the image (year)
        |image.capturedate.mon.ref_num=date of capture of the image (month)
        |image.capturedate.mday.ref_num=date of capture of the image (day of the month)
        |image.capturedate.hours.ref_num=date of capture of the image (hour)
        |image.capturedate.minutes.ref_num=date of capture of the image (minute)
        |image.capturedate.seconds.ref_num=date of capture of the image (second)
        \image.hidden.ref_num=yes/no [since 2.14]
  OR     album.name.ref_num=name of the album [since 2.13]
         image_count=total number of images in the album
         baseurl=URL of the album

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

The baseurl contains a fully-qualified URL. A URL to each image can be obtained by appending the filename of the image to this.

The name and resizedName include the type (extension), but do not include any path information.

Multiple extrafield lines with different fieldname values can be used.

If albums_too is yes, the list of results can contain album references. In this case, none of the image.*.ref_num fields will be present. Instead, album.name.ref_num will provide the reference to the sub-album. This allows reursive getting of all images in an album hierarchy.

Starting with 2.14, the protocol will honor access control and will not return full-size information if the album is set to refuse full-size and will not return non-readable albums.

5.7.8. Moving an album [since 2.7]

The move-album command asks the server to move an album to a new location within the photo gallery.

5.7.8.1. Context

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

5.7.8.2. Form data
cmd=move-album
protocol_version=2.7
set_albumName=source-album
set_destalbumName=destination-album
  • source-album is the name of the album that you intend to move;

  • destination-album is the name of the album that the source-album will be moved into, or 0 if the source-album should be moved to the root level;

5.7.8.3. Results
#__GR2PROTO__
status=result-code
status_text=explanatory-text

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

5.8. Appendix A: Response Status Codes

Table 2.1. Response Status Codes

Status nameCodeDescription
GR_STAT_SUCCESS0The 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_INVAL101The protocol major version the client is using is not supported.
GR_STAT_PROTO_MIN_VER_INVAL102The protocol minor version the client is using is not supported.
GR_STAT_PROTO_VER_FMT_INVAL103The format of the protocol version string the client sent in the request is invalid.
GR_STAT_PROTO_VER_MISSING104The request did not contain the required protocol_version key.
GR_STAT_PASSWD_WRONG201The password and/or username the client send in the request is invalid.
GR_STAT_LOGIN_MISSING202The 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_CMD301The value of the cmd key is not valid.
GR_STAT_NO_ADD_PERMISSION401The user does not have permission to add an item to the gallery.
GR_STAT_NO_FILENAME402No filename was specified.
GR_STAT_UPLOAD_PHOTO_FAIL403The file was received, but could not be processed or added to the album.
GR_STAT_NO_WRITE_PERMISSION404No write permission to destination album.
GR_STAT_NO_CREATE_ALBUM_PERMISSION501A new album could not be created because the user does not have permission to do so.
GR_STAT_CREATE_ALBUM_FAILED502A new album could not be created, for a different reason (name conflict).