Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Created a document describing the current (Version 1) gallery_remote …
…protocol.
- Loading branch information
Tim Miller
committed
Aug 22, 2002
1 parent
53f6c7a
commit bc44364
Showing
1 changed file
with
168 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,168 @@ | ||
| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> | ||
| <html> | ||
| <head> | ||
| <title>Gallery Remote Protocol version 1</title> | ||
| </head> | ||
| <body> | ||
| <h1>Gallery Remote Protocol version 1</h1> | ||
|
|
||
| <p><cite>Tim Miller</cite> <<a href="mailto:tim_miller at users.sourceforge.net">tim_miller at users dot sourceforge dot net</a>></p> | ||
|
|
||
| <p>This document describes the <a href="http://gallery.menalto.com/">gallery</a> remote application protocol, which is layered over HTTP, as of version 1.3.1 of gallery.</p> | ||
|
|
||
| <ul> | ||
| <li><a href="#summary">Summary</a></li> | ||
| <li><a href="#requests">Requests</a></li> | ||
| <li><a href="#commands">Commands</a> | ||
| <ol> | ||
| <li><a href="#login"><samp>login</samp> command</a></li> | ||
| <li><a href="#fetch-albums"><samp>fetch-albums</samp> command</a></li> | ||
| <li><a href="#add-photo"><samp>add-photo</samp> command</a></li> | ||
| </ol> | ||
| </li> | ||
| </ul> | ||
|
|
||
| <hr> | ||
| <a name="summary"> | ||
| <h2>Summary</h2> | ||
|
|
||
| <p>Gallery remote queries and sends information from a gallery installation through a protcol 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 one PHP source file, <samp><a href="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/gallery/gallery/gallery_remote.php?rev=1.6&content-type=text/vnd.viewcvs-markup">gallery_remote.php</a></samp>.</p> | ||
|
|
||
| <p>Every query from client to server corresponds to one action. Multiple actions require multiple HTTP requests.</p> | ||
|
|
||
| <p>The protocol is stateful; the client must acquire the gallery session cookie by performing a login request before any other requests will succeed.</p> | ||
|
|
||
| <p>Permissions for actions performed by gallery_remote.php are controlled in the same way they are controlled for regular web/HTML users. <samp>init.php</samp> is called at the top of each request.</p> | ||
|
|
||
| <hr> | ||
| <a name="requests"> | ||
| <h2>Requests</h2> | ||
|
|
||
| <p>Each request is expressed through an HTTP POST -- parameters are expressed as HTTP form data (control-name/current value) pairs (we'll call them "key" and "value").</p> | ||
|
|
||
| <p>Each request specifies a command (the "<samp>cmd</samp>" key). Depending on which command is specified, other parameters are required in the form-data set.</p> | ||
|
|
||
| <p>Each request also specifies a protocol version (the "<samp>protocal_version</samp>" [sic] key). If the protocol version specified by the client does not match exactly <samp>$gallery->remote_protocol_version</samp>, the request is declined. The current protocol version is "1" (it has never been changed).</p> | ||
|
|
||
| <p>Each command is described below. After a brief description of the command, template form data appears and the result format (if any) is described.</p> | ||
|
|
||
| <hr> | ||
|
|
||
| <h2>Notes</h2> | ||
| The results sections below assume a HTTP <samp>200 OK</samp> status code was returned, although a <samp>4xx</samp> or <samp>5xx</samp> result is possible. Additionally, if the protocol version is not correct, regardless of the command, an English textual error message is returned, with no other results.</p> | ||
|
|
||
| <hr> | ||
| <a name="commands"> | ||
| <h2>Commands</h2> | ||
|
|
||
| <p><strong>Note:</strong><em>The word "protocol" is misspelled in the "<samp>protocal_version</samp>" key.</em></p> | ||
|
|
||
| <ol> | ||
| <li> | ||
|
|
||
| <a name="login"> | ||
| <h3><samp>login</samp> command</h3> | ||
| <p>This command ensures a session cookie has been given to the client and, if the account information is correct, adds the proper user object to the session.</p> | ||
|
|
||
| <ul> | ||
| <li> | ||
|
|
||
| <h4>Context</h4> | ||
| <p>A request with the <samp>login</samp> command may be made at any time -- there are no prerequisites.</p> | ||
|
|
||
| </li><li> | ||
|
|
||
| <h4>Form Data</h4> | ||
| <p><samp>cmd=login<br> | ||
| protocal_version=1<br> | ||
| uname=</samp><em>gallery user name</em><samp><br> | ||
| password=</samp><em>cleartext password</em><br></p> | ||
|
|
||
| </li><li> | ||
|
|
||
| <h4>Results</h4> | ||
| <p>If the login succeeds, the value | ||
| <br> | ||
| <br><samp>SUCCESS</samp> | ||
| <br> | ||
| <br>is returned. If the login fails, the value | ||
| <br> | ||
| <br><samp>Login Incorrect</samp> | ||
| <br> | ||
| <br>is returned. If either the <samp>uname</samp> or <samp>password</samp> keys are missing, the value | ||
| <br> | ||
| <br><samp>Missing Parameters</samp> | ||
| <br> | ||
| <br>is returned.</p> | ||
|
|
||
| </li></ul> | ||
|
|
||
| </li><li> | ||
|
|
||
| <a name="fetch-albums"> | ||
| <h3><samp>fetch-albums</samp> command</h3> | ||
|
|
||
| <p>The <samp>fetch-albums</samp> command asks the server to return a list of all albums (visible with the client's logged in user permissions).</p> | ||
|
|
||
| <ul> | ||
| <li> | ||
|
|
||
| <h4>Context</h4> | ||
| <p>A request with the <samp>login</samp> command must be made before the <samp>fetch-albums</samp> command is used.</p> | ||
|
|
||
| </li><li> | ||
|
|
||
| <h4>Form Data</h4> | ||
| <p><samp>cmd=fetch-albums<br> | ||
| protocal_version=1</samp></p> | ||
|
|
||
| </li><li> | ||
|
|
||
| <h4>Results</h4> | ||
| <p>If successful, the a request using the <samp>fetch-albums</samp> command returns tab- and newline-delimited data. Each line consists of an album name, a tab character, the album title and a newline, except the last line which will contain the value<br> | ||
| <br><samp>SUCCESS</samp> | ||
| <br> | ||
| <br>If the "<samp>SUCCESS</samp>" value is not present, the list of albums should not be considered complete and the request to have failed.</p> | ||
|
|
||
| </li></ul> | ||
|
|
||
| </li><li> | ||
|
|
||
| <a name="add-photo"> | ||
| <h3><samp>add-photo</samp> command</h3> | ||
| <p>This command asks the server to add a photo to a specified album.</p> | ||
|
|
||
| <ul> | ||
| <li> | ||
|
|
||
| <h4>Context</h4> | ||
| <p>A request with the <samp>login</samp> command must be made before the <samp>fetch-albums</samp> command is used.</p> | ||
|
|
||
| </li><li> | ||
|
|
||
| <h4>Form Data</h4> | ||
| <p><samp>cmd=fetch-albums<br> | ||
| protocal_version=1<br> | ||
| set_albumName=</samp><em>album name</em><samp><br> | ||
| userfile=</samp><em>form-data-encoded image data</em><br></p> | ||
|
|
||
| </li><li> | ||
|
|
||
| <h4>Results</h4> | ||
| <p>If the file upload succeeds the value | ||
| <br> | ||
| <br><samp>SUCCESS</samp><br> | ||
| <br>is returned. If the file upload fails, a line beginning with the value<br> | ||
| <br><samp>ERROR:</samp><br> | ||
| <br>and followed by an English-language description of the reason is returned.</p> | ||
|
|
||
| </li></ul> | ||
|
|
||
| </li> | ||
|
|
||
| </ol> | ||
|
|
||
| <hr> | ||
|
|
||
| </body> | ||
| </html> |