编辑“Gallery Remote:Protocol”

__FORCETOC__

{|align=right
 |__TOC__
 |}

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

==G2 support==

The long-term plan for G2 remote access is to design a protocol based on SOAP or some other HTTP RPC protocol. However, as a stopgap, we have implemented the existing protocol 2 in G2, with some small differences.

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

* the base URL is <code><nowiki>http://www.example.com/g2_path/main.php</nowiki></code>
* an additional URL parameter needs to always be added: <code>g2_controller=remote:GalleryRemote</code>
* each parameter needs to be modified to <code>g2_form[<i>name</i>]=<i>value</i></code>.  For example, on a login request, the <i>cmd</i> parameter would be passed as <code>g2_form[cmd]=login</code>.
** except in <code>add-item</code>, where <code>userfile</code> and <code>userfile_name</code> become <code>g2_userfile</code> and <code>g2_userfile_name</code> respectively
* album "names" and image "names" are actually the unique identifier (an integer) of the object in G2, rather than an alphanumeric name
* the authToken [G2 since 2.10]

===authToken===

Starting with G2.2 (svn r15234, protocol 2.10), a new security was put in place in order to defend against cross-site request forgery attacks. G2 expects all requests to have a new URL parameter, <code>g2_authToken</code>, which contains a string. The value of that string should be the value of the <code>auth_token</code> response element to the ''previous request''.

This lets G2 make sure that a malicious script in another web page can't piggyback on the session that was created between the browser and G2, because the malicious code can't guess the authToken (it's not stored as a cookie).

All protocol responses will contain this new <code>auth_token</code> field. Usually, it's safe to assume that the authToken doesn't change throughout the lifetime of a session.

==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 (in G2, it's implemented by the <code>remote</code> module.

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 <code>[[#login|login]]</code> request before any other requests will succeed.

Because the protocol has grown organically, and was developed over the course of many years by different people, it contains many syntactic inconsistencies (sometimes parameter names use dashes, sometimes underscores, sometimes camelhumps). We apologize for these.

==Conventions==

In this document, all protocol text is denoted by a fixed-width font, like <code>login</code>. Value placeholders are additionally in italics, as in <code>status=<i>result-code</i></code>.

Along with each parameter or return value, is specified the version of the protocol when this parameter was introduced. For parameters or return values that are only supported by G2, this is also noted. Optional parameters are indicated.

'''Please note''' that the version numbers used by the Gallery 1 version of the protocol do not match the version numbers used by the Gallery 2 version of the protocol. [[#Appendix_B|Appendix B]] has a list of the major functional improvements, and the version they were introduced in G1 and G2. In general, parameters that are not supported in a given version of the protocol are just ignored. Conversely, client applications should ignore return values that they don't understand.

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

In G1, the encoding used for the data is more or less unspecified, so it is recommended to use HTML entities to encode non-ASCII characters. In G2, however, UTF-8 is always used, so plain text should be used for all strings (no HTML entities or escaping, except the escaping necessary for the Java properties file format).

==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 <code>cmd</code> 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 <code>protocol_version</code> key).

The server's response to the <code>[[#login|login]]</code> command includes the version of the protocol it implements (with the server_version key). Protocol numbers obey the following convention:

<code><i>maj</i>.<i>min</i></code>

where <code><i>maj</i></code> is the major version number and <code><i>min</i></code> is the minor version number. The current major version number is 2. Protocol 1 is no longer supported.

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.

==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 <code>#__GR2PROTO__<code>. Clients should ignore any text above this tag: it might be debug output from the server.

Each response must contain at least the keys: <code>status</code> and <code>status_text</code>.

The value associated with the status key is an integer status code (the codes are defined in [[#Appendix A|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 <code>GR_STAT_SUCCESS</code>.

The <code>status</code> key is definitive, yet the <code>status_text</code> 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|Appendix A]]).

=Commands=

==login==

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

===Request===

 cmd=login
 protocol_version=2.0
 uname=<i>gallery-user-name</i>
 password=<i>cleartext-password</i>

where <code>gallery-user-name</code> is a valid gallery user name and <code>cleartext-password</code> is the corresponding password.

===Response===

 #__GR2PROTO__
 status=<i>result-code</i>
 status_text=<i>explanatory-text</i>
 server_version=<i>major-version</i>.<i>minor-version</i>

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

==fetch-albums==

The <code>fetch-albums</code> command asks the server to return a list of all albums (visible with the client's logged in user permissions). In most cases, it's better to use [[#fetch-albums-prune|fetch-albums-prune]] because it's much faster...

===Request===

 cmd=fetch-albums
 protocol_version=2.0
 no_perms=<i>yes/no</i> [optional, G2 since 2.9]

If <code>no_perms</code> is set, then the protocol will not bother to report permissions for each album, saving chatter and a lot of load on the server. This is only supported on G2.

===Response===

         #__GR2PROTO__
         status=<i>result-code</i>
         status_text=<i>explanatory-text</i>
        /album.name.<i>ref-num</i>=<i>album-url-name</i>
        |album.title.<i>ref-num</i>=<i>album-display-name</i>
        |album.summary.<i>ref-num</i>=<i>album-summary</i> [since 2.8]
        |album.parent.<i>ref-num</i>=<i>parent-ref-num</i>
        |album.resize_size.<i>ref-num</i>=<i>image-resize-size</i> [since 2.8]
        |album.thumb_size.<i>ref-num</i>=<i>image-thumb-size</i> [since 2.9]
        |album.max_size.<i>ref-num</i>=<i>image-max-size</i> [since 2.15]
  0...n |album.perms.add.<i>ref-num</i>=<i>boolean</i>
        |album.perms.write.<i>ref-num</i>=<i>boolean</i>
        |album.perms.del_item.<i>ref-num</i>=<i>boolean</i>
        |album.perms.del_alb.<i>ref-num</i>=<i>boolean</i>
        |album.perms.create_sub.<i>ref-num</i>=<i>boolean</i>
        \album.info.extrafields.<i>ref-num</i>=<i>extra-fields</i> [since 2.3]
         album_count=<i>number-of-albums</i>
       	can_create_root=<i>yes/no</i> [since 2.11]

If the <code>status</code> is equal to <code>GR_STAT_SUCCESS</code>, the album data was fetched successfully.

If successful, a response to the <code>fetch-albums</code> command returns several keys for each album in the gallery, where:

* <code><i>ref-num</i></code> is a reference number,
* <code><i>album-url-name</i></code> is the name of the partial URL for the gallery,
* <code><i>album-display-name</i></code> is the gallery's visual name,
* <code><i>album-summary</i></code> is the summary of the album,
* <code><i>parent-ref-num</i></code> refers to some other album's ref-num. A <code><i>parent-ref-num</i></code> of <code>0</code> (zero) indicates that the album is a "top-level" album (it has no parent).
* <code><i>image-resize-size</i></code> is the intermediate size of images created when a large image is added to an album,
* <code><i>image-max-size</i></code> is the maximum size of images created when a large image is added to an album,
* <code><i>extra-fields</i></code> is a comma-separated list of extra fields names,
* and <code><i>boolean</i></code> represents a boolean value: <code>true</code> 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 <code>add permission</code> allows the user to add a picture to the album.
* the <code>write permission</code> allows the user to add and change pictures in the album.
* the <code>del_item permission</code> allows the user remove pictures from the album.
* the <code>del_alb permission</code> allows the user to delete the album.
* the <code>create_sub permission</code> allows the user to create nested albums in the album.

The number of albums in the response is returned as <code><i>number-of-albums</i></code>.

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

==fetch-albums-prune==

'''since 2.2'''

The <code>fetch-albums-prune</code> 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 <code>[[#fetch-albums|fetch-albums]]</code> is two-fold: the previous version was slow on the server-side, because of the way it was structured, and limitations 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.

===Request===

 cmd=fetch-albums-prune
 protocol_version=2.2
 no_perms=<i>yes/no</i> [optional, G2 since 2.9]

If <code>no_perms</code> is set, then the protocol will not bother to report permissions for each album, saving chatter and a lot of load on the server. This is only supported on G2.

===Response===

         #__GR2PROTO__
         status=<i>result-code</i>
         status_text=<i>explanatory-text</i>
        /album.name.<i>ref-num</i>=<i>album-url-name</i>
        |album.title.<i>ref-num</i>=<i>album-display-name</i>
        |album.summary.<i>ref-num</i>=<i>album-summary</i> [since 2.8]
        |album.parent.<i>ref-num</i>=<i>parent-ref-num</i>
        |album.resize_size.<i>ref-num</i>=<i>image-resize-size</i> [since 2.8]
        |album.thumb_size.<i>ref-num</i>=<i>image-thumb-size</i> [since 2.9]
        |album.max_size.<i>ref-num</i>=<i>image-max-size</i> [since 2.15]
  0...n |album.perms.add.<i>ref-num</i>=<i>boolean</i>
        |album.perms.write.<i>ref-num</i>=<i>boolean</i>
        |album.perms.del_item.<i>ref-num</i>=<i>boolean</i>
        |album.perms.del_alb.<i>ref-num</i>=<i>boolean</i>
        |album.perms.create_sub.<i>ref-num</i>=<i>boolean</i>
        \album.info.extrafields.<i>ref-num</i>=<i>extra-fields</i> [since 2.3]
         album_count=<i>number-of-albums</i>
       	can_create_root=<i>yes/no</i> [since 2.11]

If the <code>status</code> is equal to <code>GR_STAT_SUCCESS</code>, the album data was fetched successfully.

If successful, a response to the <code>fetch-albums</code> command returns several keys for each album in the gallery, where:

* <code><i>ref-num</i></code> is a reference number,
* <code><i>album-url-name</i></code> is the name of the partial URL for the gallery,
* <code><i>album-display-name</i></code> is the gallery's visual name,
* <code><i>album-summary</i></code> is the summary of the album,
* <code><i>parent-ref-num</i></code> refers to some other album's ref-num. A <code><i>parent-ref-num</i></code> of <code>0</code> (zero) indicates that the album is a "top-level" album (it has no parent). Be aware: oppositional to this description Gallery Remote expects the <code><i>album-url-name</i></code> instead of <code><i>parent-ref-num</i></code>. This seems to be a bug according to this documentation.
* <code><i>image-resize-size</i></code> is the intermediate size of images created when a large image is added to an album,
* <code><i>image-max-size</i></code> is the maximum size of images created when a large image is added to an album,
* <code><i>extra-fields</i></code> is a comma-separated list of extra fields names,
* and <code><i>boolean</i></code> represents a boolean value: <code>true</code> 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 <code>add permission</code> allows the user to add a picture to the album.
* the <code>write permission</code> allows the user to add and change pictures in the album.
* the <code>del_item permission</code> allows the user remove pictures from the album.
* the <code>del_alb permission</code> allows the user to delete the album.
* the <code>create_sub permission</code> allows the user to create nested albums in the album.

The number of albums in the response is returned as <code><i>number-of-albums</i></code>.

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

==add-item==

The add-item command asks the server to add a photo to a specified album. It's usually necessary to have previously sent a <code>login</code> request.

===Request===

 cmd=add-item
 protocol_version=2.0
 set_albumName=<i>album name</i>
 userfile=<i>user-file</i>
 userfile_name=<i>file-name</i>
 caption=<i>caption</i> [optional]
 force_filename=<i>force-filename</i> [optional]
 auto_rotate=<i>yes/no</i> [optional, since 2.5]
 extrafield.<i>fieldname</i>=<i>fieldvalue</i> [optional, since 2.3]

* <code><i>file-name</i></code> is usually inserted automatically by HTTP library, which is why we also have force_filename, so the client can override the default file name;
* <code><i>user-file</i></code> can be either
** <code>form-data-encoded</code> image data [since 2.0]
** URL of image [since 2.12]
* Multiple <code>extrafield.</code> lines with different <code><i>fieldname</i></code> values can be used.
* Only gallery administrators can specify a URL as the <code>userfile</code>. This is not supported in G2.
* Note than in G2, the userfile parameter is <code>g2_userfile</code>, not <code>g2_form[userfile]</code>
* <code>auto_rotate</code> is not supported in G2.

===Response===

 #__GR2PROTO__
 status=<i>result-code</i>
 status_text=<i>explanatory-text</i>
 item_name=<i>name-of-new-item</i> [G2 since 2.7]

* If the <code>status</code> is equal to <code>GR_STAT_SUCCESS</code>, the file upload succeeded.
* <code><i>name-of-new-item</i></code> is the name (or rather the Id) of the newly created item (only available in G2).

==album-properties==

The <code>album-properties</code> command asks the server for information about an album.

===Request===

 cmd=album-properties
 protocol_version=2.0
 set_albumName=<i>album-name</i>

===Response===

 #__GR2PROTO__
 status=<i>result-code</i>
 status_text=<i>explanatory-text</i>
 auto_resize=<i>resize-dimension</i>
 max_size=<i>max-dimension</i> [since 2.15]
 add_to_beginning=<i>yes/no</i> [since 2.10]
 extrafields=<i>comma-separated extra fields</i> [G2 since 2.13]

* If the <code>status</code> is equal to <code><i>GR_STAT_SUCCESS</i></code>, the request succeeded.

* If an image is uploaded such that its largest dimension is greater than <code><i>max-dimension</i></code>, 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 dependent on the size of the image that was uploaded. If the value is <code>0</code> (zero), the Gallery server does not intend to resize uploaded images.

* <code>add_to_beginning</code> will contain <code>yes</code> or <code>no</code> based on whether the album will add images to the beginning or the end of the album.

==new-album==

'''since 2.1'''

The <code>new-album</code> command asks the server to add a new album to the gallery installation.

===Request===

 cmd=new-album
 protocol_version=2.1
 set_albumName=<i>parent-album-name</i>
 newAlbumName=<i>album-name</i> [optional]
 newAlbumTitle=<i>album-title</i> [optional]
 newAlbumDesc=<i>album-description</i> [optional]

* <code><i>parent-album-name</i></code> is the name of the album inside which the new album should be created, or 0 to create the album at the top-level;
* <code><i>album-name</i></code> is the new album's desired name. The name must be unique within the Gallery (or in G2 within the parent album). 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;
* <code><i>album-title</i></code> is the new album's desired title;
* <code><i>album-description</i></code> is the new album's desired description.

===Response===

 #__GR2PROTO__
 status=<i>result-code</i>
 status_text=<i>explanatory-text</i>
 album_name=<i>actual-name</i> [since 2.5]

*If the <code><i>result-code</i></code> is equal to <code>GR_STAT_SUCCESS</code>, the request succeeded.

*If the <code><i>result-code</i></code> is equal to <code>GR_STAT_NO_CREATE_ALBUM_PERMISSION</code>, 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 <code><i>album-title</i></code> is left blank, Gallery will automatically generate an album name. <code><i>actual-name</i></code> will return the name of the newly created album.

==fetch-album-images==
'''since 2.4'''

The <code>fetch-album-images</code> command asks the server to return information about all the images (and optionally sub-albums) that are direct children of an album.

A request with the login command can be made before the <code>fetch-album-images</code> 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.

===Request===

 cmd=fetch-album-images
 protocol_version=2.4
 set_albumName=<i>album-name</i>
 albums_too=<i>yes/no</i> [optional, since 2.13]
 random=<i>yes/no</i> [optional, G2 since ***]
 limit=<i>number-of-images</i> [optional, G2 since ***]
 extrafields=<i>yes/no</i> [optional, G2 since 2.12]

* If <code><i>set_albumName</i></code> is empty, the root albums are listed. Of course, this only works in G1 if <code>albums_too</code> is true, since no pictures are in the root album.
* <code>albums_too</code> determines whether the command returns only pictures, or also sub-albums. 
* If <code>random</code> is set to <code>yes</code>, Gallery will return GalleryPhotoItems from this album and its descendants. <code>limit</code> must also be set for this to work, and it determines how many pictures will be returned. If <code>random</code> is not set, <code>limit</code> is ignored.
* In G2 since 2.12, if <code>extrafields</code> is <code>yes</code>, extra fields (Summary and Description) are returned. In G1, extra fields are always returned.

===Response===

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

* If the <code><i>result-code</i></code> is equal to <code>GR_STAT_SUCCESS</code>, the request succeeded.
* The <code><i>baseurl</i></code> contains a fully-qualified URL. A URL to each image can be obtained by appending the filename of the image to this.
* The <code>name</code> and <code>resizedName</code> include the type (extension), but do not include any path information.
* Multiple <code>extrafield</code> lines with different <code><i>fieldname</i></code> values can be used.
* If <code>albums_too</code> is <code>yes</code>, the list of results can contain album references. In this case, none of the <code>image.<i>*</i>.<i>ref-num</i></code> fields will be present. Instead, <code>album.name.<i>ref-num</i></code> will provide the reference to the sub-album. This allows recursive fetching 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.

==move-album==

'''since 2.7; not supported for G2'''

The <code>move-album</code> command asks the server to move an album to a new location within the Gallery.

===Request===

 cmd=move-album
 protocol_version=2.7
 set_albumName=<i>source-album</i>
 set_destalbumName=<i>destination-album</i>

* <code><i>source-album</i></code> is the name of the album that you intend to move;
* <code><i>destination-album</i></code> is the name of the album that the <code><i>source-album</i></code> will be moved into, or <code>0</code> if it should be moved to the root level;

===Response===

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

If the <code><i>result-code</i></code> is equal to <code>GR_STAT_SUCCESS</code>, the album move succeeded.

==increment-view-count==

'''only in G2'''

The <code>increment-view-count</code> command informs the Gallery that the user has viewed a given item. It should be called by slideshow applications, for example. Applications that run unattended (screen savers) should probably not call it...

===Request===

 cmd=increment-view-count
 protocol_version=****
 itemId=<i>item-id</i>

===Response===

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

If the <code><i>result-code</i></code> is equal to <code>GR_STAT_SUCCESS</code>, the view count was successfully incremented.

==image-properties==

'''only in G2'''

The <code>image-properties</code> command returns information about one image, in similar fashion as the <code>[[#fetch-album-images|fetch-album-images]]</code> command...

===Request===

 cmd=image-properties
 protocol_version=***
 id=<i>item-id</i>

<code>item-id</code> must be a valid unique identifier for either a <code>GalleryPhotoItem</code> or a <code>GalleryAlbumItem</code>.

===Response===

 #__GR2PROTO__
 status=result-code
 status_text=explanatory-text
 image.name=filename of the image
 image.raw_width=the width of the full-sized image
 image.raw_height=the height of the full-sized image
 image.raw_filesize=size of the full-sized image
 image.resizedName=filename of the resized image, if there is one
 image.resized_width=the width of the resized image, if there is one
 image.resized_height=the height of the resized image, if there is one
 image.thumbName=filename of the thumbnail
 image.thumb_width=the width of the thumbnail
 image.thumb_height=the height of the thumbnail
 image.caption=caption associated with the image
 image.title=title associated with the image
 image.forceExtension=the extension of the image
 image.hidden=yes/no

* If the <code><i>result-code</i></code> is equal to <code>GR_STAT_SUCCESS</code>, image was found and properties returned.
* The <code>name</code> and <code>resizedName</code> include the type (extension), but do not include any path information.
* If the <code>id</code> parameter in the request corresponds to a <code>GalleryAlbumItem</code>, only the <code>image.thumbname</code>, <code>image.thumb_width</code> and <code>image.thumb_height</code> will be returned.

==no-op==

'''only in G2'''

The <code>no-op</code> command doesn't do anything. It can be used by clients to verify that the module is operational.

===Request===

 cmd=no-op

===Response===

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

If the <code><i>result-code</i></code> is equal to <code>GR_STAT_SUCCESS</code>, the remote module is operational.

=3rd Party Client Software/Libraries=
This section contains information/experiences relating to miscellaneous libraries and software environments used to connect to Gallery installations for the purposes of invoking Remote Protocol methods.

==Delphi==
The [[GLoSS]] screensaver and desktop changer for Gallery is written in Delphi, and currently uses version 9.00.10 of the open source Indy library for interacting via the Remote Protocol.  During testing of GLoSS with G2.2RC1 (specifically the new authToken response introduced in 2.10), an issue was found where the Indy TIdHTTP component was not returning the authToken value passed back from calls to the Remote Protocol [[#login|login]] method.
From a perusal of code from both the Indy library and Gallery's GalleryRemote.inc file from the Remote module, it appears that Gallery is not considering the first Get from the TIdHTTP component in any session to be "persistent", so is not returning the authToken.
Use the Indy library with caution.

=Appendix A=

{| border="1" cellspacing="0"
|+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.
|-
|PROTO_MAJ_VER_INVAL
||101
||The protocol major version the client is using is not supported.
|-
|PROTO_MIN_VER_INVAL
||102
||The protocol minor version the client is using is not supported.
|-
|PROTO_VER_FMT_INVAL
||103
||The format of the protocol version string the client sent in the request is invalid.
|-
|PROTO_VER_MISSING
||104
||The request did not contain the required protocol_version key.
|-
|PASSWD_WRONG
||201
||The password and/or username the client send in the request is invalid.
|-
|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.
|-
|UNKNOWN_CMD
||301
||The value of the cmd key is not valid.
|-
|NO_ADD_PERMISSION
||401
||The user does not have permission to add an item to the gallery.
|-
|NO_FILENAME
||402
||No filename was specified.
|-
|UPLOAD_PHOTO_FAIL
||403
||The file was received, but could not be processed or added to the album.
|-
|NO_WRITE_PERMISSION
||404
||No write permission to destination album.
|-
|NO_VIEW_PERMISSION
||405
||No view permission for this image.
|-
|NO_CREATE_ALBUM_PERMISSION
||501
||A new album could not be created because the user does not have permission to do so.
|-
|CREATE_ALBUM_FAILED
||502
||A new album could not be created, for a different reason (name conflict).
|-
|MOVE_ALBUM_FAILED
||503
||The album could not be moved.
|-
|ROTATE_IMAGE_FAILED
||504
||The image could not be rotated
|}

=Appendix B=

Protocol version numbers reported by G1 and G2 do not match! This table attempts to elucidate which version of the protocol supports each feature, for G1 and G2.

{| border="1" cellspacing="0"
|+Feature to version number mapping
!Feature code!! Feature description !! G1 !! G2
|-
|CAPA_UPLOAD_FILES
|Upload new files (<code>[[#add-item|add-item]]</code>)
|2.0
|2.2
|-
|CAPA_FETCH_ALBUMS
|Download the list of albums (<code>[[#fetch-albums|fetch-albums]]</code>)
|2.0
|2.2
|-
|CAPA_UPLOAD_CAPTION
|Set a caption in <code>[[#add-item|add-item]]</code>
|2.0
|2.2
|-
|CAPA_FETCH_HIERARCHICAL
|Fetch albums in an orderly fashion in <code>[[#fetch-albums|fetch-albums]]</code>
|2.0
|2.2
|-
|CAPA_ALBUM_INFO
|Get information about a specific album (<code>[[#album-properties|album-properties]]</code>)
|2.0
|2.6
|-
|CAPA_NEW_ALBUM
|Create new album (<code>[[#new-album|new-album]]</code>)
|2.1
|2.3
|-
|CAPA_FETCH_ALBUMS_PRUNE
|Download the list of albums more efficiently (<code>[[#fetch-albums-prune|fetch-albums-prune]]</code>)
|2.2
|2.2
|-
|CAPA_FORCE_FILENAME
|Set the name of the file in <code>[[#add-item|add-item]]</code>
|2.5
|2.4
|-
|CAPA_FETCH_ALBUM_IMAGES
|Download the list of images in an album (<code>[[#fetch-album-images|fetch-album-images]]</code>)
|2.9
|2.4
|-
|CAPA_MOVE_ALBUM
|Move an album to a different parent album (<code>[[#move-album|move-album]]</code>)
|2.7
|x
|-
|CAPA_FETCH_ALBUMS_TOO
|Get sub-albums in <code>[[#fetch-album-images|fetch-album-images]]</code>
|2.13
|2.8
|-
|CAPA_FETCH_NON_WRITEABLE_ALBUMS
|Always get albums that are not writable in <code>[[#fetch-albums|fetch-albums]]</code>
|after 2.13
|always
|-
|CAPA_FETCH_HONORS_HIDDEN
|Hidden images are not listed in <code>[[#fetch-album-images|fetch-album-images]]</code>
|2.14
|always
|-
|CAPA_IMAGE_MAX_SIZE
|Report the maximum image size for the album in <code>[[#album-properties|album-properties]]</code>
|2.15
|2.6
|-
|CAPA_INCREMENT_VIEW_COUNT
|Increment an image's view count (<code>[[#increment-view-count|increment-view-count]]</code>)
|x
|2.7
|-
|CAPA_FETCH_RANDOM
|Download random images in <code>[[#fetch-album-images|fetch-album-images]]</code>
|x
|2.9
|}

=Appendix C=

This change log only contains changes posterior to November 2006.

{| border="1" cellspacing="0"
|+Change log
! Date !! Change description !! G1 !! G2
|-
|19/11/06
|Added support for the new [[#G2_Support|G2 authToken]] security
|
|2.10
|-
|23/11/06
|<code>[[#fetch-album-images|fetch-album-images]]</code> returns <code>album.caption</code>
|
|2.11
|-
|06/02/08
|<code>[[#fetch-album-images|fetch-album-images]]</code> optionally returns <code>extrafields</code>
|
|2.12
|-
|12/02/08
|<code>[[#album-properties|album-properties]]</code> returns <code>extrafields</code>
|
|2.13
|}