編輯“Gallery Remote:Protocol”（章節(jié)）

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