/
gal_remote_proto-2.html
276 lines (231 loc) · 12.4 KB
/
gal_remote_proto-2.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>Gallery Remote Protocol version 2</title>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<style type="text/css">
h1 { font-family: sans-serif; font-size: 17pt; font-weight: bold; }
h2 { font-family: sans-serif; font-size: 14pt; font-weight: bold; }
h3 { font-family: sans-serif; font-size: 12pt; font-weight: bold; }
h4 { font-family: sans-serif; font-size: 11pt; font-weight: bold; }
p,ol,ul,body{ font-family: serif; font-size: 11pt; }
li { font-family: serif; font-size: 11pt; margin: 4px; }
.since { background-color: #FFcccc; color: #FF0000; }
samp { font-family: monospace; color: #0000aa; background-color: #FFFF99; }
body { background-color: #FFFFFF; margin: 8px; }
hr { color: black; height: 1px; width: 100%; }
table { border-style: solid; border-width: 1px; border-color: black; margin: 20px; }
td {
border-style: solid;
border-width: 1px;
border-color: black;
padding: 9px; }
img { border-width: 0px; }
</style>
</head>
<body>
<h1>Gallery Remote Protocol version 2</h1>
<p><cite>Tim Miller</cite> <<a href="mailto:tim_miller at users.sourceforge.net">tim_miller
at users dot sourceforge dot net</a>><br>
<cite>Pierre-Luc Paour</cite> <<a href="mailto:paour at users.sourceforge.net">paour
at users dot sourceforge dot net</a>></p>
<hr>
<h2><a name="toc" />Contents</h2>
<ul>
<li>1. <a href="#intro">Introduction</a></li>
<li>2. <a href="#overview">Overview</a></li>
<li>3. <a href="#interaction">Client-Server Interaction</a></li>
<li>4. <a href="#requests">Requests</a></li>
<li>5. <a href="#responses">Responses</a></li>
<li>6. <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-item"><samp>add-item</samp> command</a></li>
<li><a href="#album-info"><samp>album-info</samp> command</a></li>
</ol>
</li>
<li>Appendix A: <a href="#appendix_a">Response Status Codes</a></li>
</ul>
<hr>
<h2><a name="intro" />1. Introduction</h2>
<p>This document describes the new <a href="http://gallery.menalto.com/">Gallery</a>
remote application protocol, which is layered over HTTP, as of version 1.3.2
of Gallery.</p>
<p>Also see documentation of the <a href="gal_remote_proto-1.html">previous version</a>
of the protocol.</p>
<hr>
<h2><a name="overview" />2. Overview</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 the PHP source file <samp><a href="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/gallery/gallery/gallery_remote2.php?rev=1.6&content-type=text/vnd.viewcvs-markup">gallery_remote2.php</a></samp>.</p>
<p>Each 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_remote2.php are controlled in
the same way they are controlled for regular web/HTML users. <samp>init.php</samp>
is called before each request is processed by the server.</p>
<hr>
<h2><a name="interaction" />3. Client-Server Interaction</h2>
<p>All client-server interaction follows the standard HTTP model. The client initiates all interactions with a <em><a href="#requests">request</a></em>. The server always responds with one <em><a href="#responses">response</a></em>. 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.</p>
<p>Each request specifies a <em><a href="#commands">command</a></em> value (and possibly some corresponding parameters) which determines the content of the response.Command-specific responses are defined in the context of each <em>command</em> below).</p>
<hr>
<h2><a name="requests" />4. 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 key/value pairs are required in the form-data set (the parameters).</p>
<p>Each request also specifies a protocol version (the <samp>protocol_version</samp>
key).</p>
<p>The server's response to the <a href="#login">login</a> command includes the version of the protocol it implements (with the <samp>server_version</samp> key). Protocol
numbers obey the following convention:<br><br><em>maj</em><samp>.</samp><em>min</em> <br><br>
where <em>maj</em> is the major version number and <em>min</em> is the minor
version number. Different major versions of the protocol use different <samp>gallery_remote</samp><em>maj</em><samp>.php</samp>
files. Each such file may provide support for various minor versions.</p>
<p>Each command is described in the <a href="#commands">Commands</a> section below. After a brief description of the command, template form data appears and the contents of the server's response is described.</p>
<hr>
<h2><a name="responses" />5. Responses</h2>
<p>After the client POSTs a request, the server sends a <em>response</em> to the client. The format of the response is a key/value format compatible with the Java "<a href="http://java.sun.com/j2se/1.4.1/docs/api/java/util/Properties.html">Properties</a>" stream format.</p>
<p>Each response contains at least the keys: <samp>status</samp> and <samp>status_text</samp>.</p>
<p>The value associated with the status key is an integer status code. If the server was able to complete the command in the client's request, The status will be <samp>0</samp> (zero).</p>
<p>The <samp>status</samp> key is definitive, yet the <samp>status_text</samp> may contain human-readable additional information (but will likely be English language only).</p>
<p>Otherwise, if the server was not able to successfully complete the request, the status will be a non-zero integer (see <a href="#appendix_a">Appendix A: Response Status Codes</a>).
</p>
<hr>
<h2><a name="commands" />6. Commands</h2>
<ol>
<li>
<h3><a name="login" /><samp>login</samp> command</h3>
<p>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.</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>
protocol_version=2.0</samp><em></em><br>
<samp>uname=</samp><em>Gallery user name</em><samp><br>
password=</samp><em>cleartext password</em><br>
</p>
</li>
<li>
<h4>Results</h4>
<p>
<samp>status=</samp>result code<br>
<samp>server_version=</samp><em>major-version</em><samp>.</samp><em>minor-version</em><br>
</p>
<p>If the <samp>status</samp> key's value is 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.
</p>
</li>
</ul>
</li>
<li>
<h3><a name="fetch-albums" /><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>
protocol_version=2.0</samp></p>
</li>
<li>
<h4>Results</h4>
<p>If the <samp>status</samp> key's value is 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.
</p>
<p>If successful, a request using the <samp>fetch-albums</samp> command
returns three keys for each album in the gallery:<br><br>
<samp>album.name.</samp><em>ref-num</em><samp>=</samp><em>album-url-name</em><br>
<samp>album.title.</samp><em>ref-num</em><samp>=</samp><em>album-display-name</em><br>
<samp>album.parent.</samp><em>ref-num</em><samp>=</samp><em>parent-ref-num</em><br><br>
where
<ul>
<li><em>ref-num</em> is a reference number,</li>
<li><em>album-url-name</em> is the name of the partial URL for the gallery,</li>
<li><em>album-display-name</em> is the gallery's visual name,</li>
<li>and <em>parent-ref-num</em> refers to some other album's <em>ref-num</em>.</li>
</ul><br>
A <em>parent-ref-num</em> of <samp>0</samp> indicates that the album is a "top-level" album (it has no parent).</p>
</li>
</ul>
</li>
<li>
<h3><a name="add-item" /><samp>add-item</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>add-item</samp> command is used.</p>
</li>
<li>
<h4>Form Data</h4>
<p><samp>cmd=add-item<br>
protocol_version=2.0<br>
set_albumName=</samp><em>album name</em><samp><br>
userfile=</samp><em>form-data-encoded image data</em><br>
<samp>caption=</samp><em>caption</em> [since 2.0]<br>
<samp>force_filename=</samp><em>name of the file on the server</em>
[since 2.0]</p>
</li>
<li>
<h4>Results</h4>
<p>If the <samp>status</samp> key's value is GR_STAT_SUCCESS, the the file upload succeeded.
</p>
</li>
</ul>
</li>
<li>
<h3><a name="album-info" id="album-info" /><samp>album-info</samp> command [since 2.0]</h3>
<p>This command asks the server for information on an album.</p>
<ul>
<li>
<h4>Context</h4>
<p>A request with the <samp>login</samp> command must be made before the
<samp>album-info</samp> command is used.</p>
</li>
<li>
<h4>Form Data</h4>
<p><samp>cmd=album-info<br>
protocol_version=2.0<br>
set_albumName=</samp><em>album name</em></p>
</li>
<li>
<h4>Results</h4>
<p>If the <samp>status</samp> key's value is GR_STAT_SUCCESS, the the request succeeded.
</p>
<p><samp>auto-resize=</samp>size, in pixels, to which the server will resize pictures on upload.</p><p>If the value is <samp>0</samp>, Gallery will not resize uploaded images.</p>
</li>
</ul>
</li>
</ol>
<hr>
<h2><a name="appendix_a" />Appendix A: Response Status Codes</h2>
<table>
<thead>
<tr>
<th>Status name</th>
<th>Code</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr><td>GR_STAT_SUCCESS</td><td>0</td><td>The command the client sent in the request completed successfully. The data (if any) in the response should be considered valid.</td></tr>
<tr><td>GR_STAT_PROTO_MAJ_VER_INVAL</td><td>101</td><td>The protocol major version the client is using is not supported.</td></tr>
<tr><td>GR_STAT_PROTO_MIN_VER_INVAL</td><td>102</td><td>The protocol minor version the client is using is not supported.</td></tr>
<tr><td>GR_STAT_PROTO_VER_FMT_INVAL</td><td>103</td><td>The format of the protocol version string the client sent in the request is invalid.</td></tr>
<tr><td>GR_STAT_PROTO_VER_MISSING</td><td>104</td><td>The request did not contain the required <samp>protocol_version</samp> key.</td></tr>
<tr><td>GR_STAT_PASSWD_WRONG</td><td>201</td><td>The password and/or username the client send in the request is invalid.</td></tr>
<tr><td>GR_STAT_LOGIN_MISSING</td><td>202</td><td>The client used the login command in the request but failed to include either the username or password (or both) in the request.</td></tr>
</tbody>
</table>
</body>
</html>