Subversion
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
svn_ra_svn.h
Go to the documentation of this file.
1 /**
2  * @copyright
3  * ====================================================================
4  * Licensed to the Apache Software Foundation (ASF) under one
5  * or more contributor license agreements. See the NOTICE file
6  * distributed with this work for additional information
7  * regarding copyright ownership. The ASF licenses this file
8  * to you under the Apache License, Version 2.0 (the
9  * "License"); you may not use this file except in compliance
10  * with the License. You may obtain a copy of the License at
11  *
12  * http://www.apache.org/licenses/LICENSE-2.0
13  *
14  * Unless required by applicable law or agreed to in writing,
15  * software distributed under the License is distributed on an
16  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17  * KIND, either express or implied. See the License for the
18  * specific language governing permissions and limitations
19  * under the License.
20  * ====================================================================
21  * @endcopyright
22  *
23  * @file svn_ra_svn.h
24  * @brief libsvn_ra_svn functions used by the server
25  */
26 
27 #ifndef SVN_RA_SVN_H
28 #define SVN_RA_SVN_H
29 
30 #include <apr.h>
31 #include <apr_pools.h>
32 #include <apr_hash.h>
33 #include <apr_tables.h>
34 #include <apr_file_io.h> /* for apr_file_t */
35 #include <apr_network_io.h> /* for apr_socket_t */
36 
37 #include "svn_types.h"
38 #include "svn_string.h"
39 #include "svn_config.h"
40 #include "svn_delta.h"
41 
42 #ifdef __cplusplus
43 extern "C" {
44 #endif /* __cplusplus */
45 
46 /** The well-known svn port number. */
47 #define SVN_RA_SVN_PORT 3690
48 
49 /** Currently-defined capabilities. */
50 #define SVN_RA_SVN_CAP_EDIT_PIPELINE "edit-pipeline"
51 #define SVN_RA_SVN_CAP_SVNDIFF1 "svndiff1"
52 #define SVN_RA_SVN_CAP_ABSENT_ENTRIES "absent-entries"
53 /* maps to SVN_RA_CAPABILITY_COMMIT_REVPROPS: */
54 #define SVN_RA_SVN_CAP_COMMIT_REVPROPS "commit-revprops"
55 /* maps to SVN_RA_CAPABILITY_MERGEINFO: */
56 #define SVN_RA_SVN_CAP_MERGEINFO "mergeinfo"
57 /* maps to SVN_RA_CAPABILITY_DEPTH: */
58 #define SVN_RA_SVN_CAP_DEPTH "depth"
59 /* maps to SVN_RA_CAPABILITY_LOG_REVPROPS */
60 #define SVN_RA_SVN_CAP_LOG_REVPROPS "log-revprops"
61 /* maps to SVN_RA_CAPABILITY_PARTIAL_REPLAY */
62 #define SVN_RA_SVN_CAP_PARTIAL_REPLAY "partial-replay"
63 /* maps to SVN_RA_CAPABILITY_ATOMIC_REVPROPS */
64 #define SVN_RA_SVN_CAP_ATOMIC_REVPROPS "atomic-revprops"
65 
66 /** ra_svn passes @c svn_dirent_t fields over the wire as a list of
67  * words, these are the values used to represent each field.
68  *
69  * @defgroup ra_svn_dirent_fields Definitions of ra_svn dirent fields
70  * @{
71  */
72 
73 /** The ra_svn way of saying @c SVN_DIRENT_KIND. */
74 #define SVN_RA_SVN_DIRENT_KIND "kind"
75 
76 /** The ra_svn way of saying @c SVN_DIRENT_SIZE. */
77 #define SVN_RA_SVN_DIRENT_SIZE "size"
78 
79 /** The ra_svn way of saying @c SVN_DIRENT_HAS_PROPS. */
80 #define SVN_RA_SVN_DIRENT_HAS_PROPS "has-props"
81 
82 /** The ra_svn way of saying @c SVN_DIRENT_CREATED_REV. */
83 #define SVN_RA_SVN_DIRENT_CREATED_REV "created-rev"
84 
85 /** The ra_svn way of saying @c SVN_DIRENT_TIME. */
86 #define SVN_RA_SVN_DIRENT_TIME "time"
87 
88 /** The ra_svn way of saying @c SVN_DIRENT_LAST_AUTHOR. */
89 #define SVN_RA_SVN_DIRENT_LAST_AUTHOR "last-author"
90 
91 /** @} */
92 
93 /** A value used to indicate an optional number element in a tuple that was
94  * not received.
95  */
96 #define SVN_RA_SVN_UNSPECIFIED_NUMBER ~((apr_uint64_t) 0)
97 
98 /** A specialized form of @c SVN_ERR to deal with errors which occur in an
99  * svn_ra_svn_command_handler().
100  *
101  * An error returned with this macro will be passed back to the other side
102  * of the connection. Use this macro when performing the requested operation;
103  * use the regular @c SVN_ERR when performing I/O with the client.
104  */
105 #define SVN_CMD_ERR(expr) \
106  do { \
107  svn_error_t *svn_err__temp = (expr); \
108  if (svn_err__temp) \
109  return svn_error_create(SVN_ERR_RA_SVN_CMD_ERR, \
110  svn_err__temp, NULL); \
111  } while (0)
112 
113 /** an ra_svn connection. */
114 typedef struct svn_ra_svn_conn_st svn_ra_svn_conn_t;
115 
116 /** Command handler, used by svn_ra_svn_handle_commands(). */
117 typedef svn_error_t *(*svn_ra_svn_command_handler)(svn_ra_svn_conn_t *conn,
118  apr_pool_t *pool,
119  apr_array_header_t *params,
120  void *baton);
121 
122 /** Command table, used by svn_ra_svn_handle_commands().
123  */
125 {
126  /** Name of the command */
127  const char *cmdname;
128 
129  /** Handler for the command */
131 
132  /** Termination flag. If set, command-handling will cease after
133  * command is processed. */
136 
137 /** Memory representation of an on-the-wire data item. */
138 typedef struct svn_ra_svn_item_t
139 {
140  /** Variant indicator. */
141  enum {
142  SVN_RA_SVN_NUMBER,
143  SVN_RA_SVN_STRING,
144  SVN_RA_SVN_WORD,
145  SVN_RA_SVN_LIST
146  } kind;
147  /** Variant data. */
148  union {
149  apr_uint64_t number;
150  svn_string_t *string;
151  const char *word;
152 
153  /** Contains @c svn_ra_svn_item_t's. */
154  apr_array_header_t *list;
155  } u;
157 
158 typedef svn_error_t *(*svn_ra_svn_edit_callback)(void *baton);
159 
160 /** Initialize a connection structure for the given socket or
161  * input/output files.
162  *
163  * Either @a sock or @a in_file/@a out_file must be set, not both.
164  * Specify the desired network data compression level (zlib) from
165  * 0 (no compression) to 9 (best but slowest).
166  *
167  * @since New in 1.7.
168  */
170 svn_ra_svn_create_conn2(apr_socket_t *sock,
171  apr_file_t *in_file,
172  apr_file_t *out_file,
173  int compression_level,
174  apr_pool_t *pool);
175 
176 /** Similar to svn_ra_svn_create_conn2() but uses default
177  * compression level (#SVN_DELTA_COMPRESSION_LEVEL_DEFAULT) for network
178  * transmissions.
179  *
180  * @deprecated Provided for backward compatibility with the 1.6 API.
181  */
184 svn_ra_svn_create_conn(apr_socket_t *sock,
185  apr_file_t *in_file,
186  apr_file_t *out_file,
187  apr_pool_t *pool);
188 
189 /** Add the capabilities in @a list to @a conn's capabilities.
190  * @a list contains svn_ra_svn_item_t entries (which should be of type
191  * SVN_RA_SVN_WORD; a malformed data error will result if any are not).
192  *
193  * This is idempotent: if a given capability was already set for
194  * @a conn, it remains set.
195  */
196 svn_error_t *
198  const apr_array_header_t *list);
199 
200 /** Return @c TRUE if @a conn has the capability @a capability, or
201  * @c FALSE if it does not. */
204  const char *capability);
205 
206 /** Return the data compression level to use for network transmissions
207  *
208  * @since New in 1.7.
209  */
210 int
212 
213 /** Returns the remote address of the connection as a string, if known,
214  * or NULL if inapplicable. */
215 const char *
217 
218 /** Write a number over the net.
219  *
220  * Writes will be buffered until the next read or flush.
221  */
222 svn_error_t *
224  apr_pool_t *pool,
225  apr_uint64_t number);
226 
227 /** Write a string over the net.
228  *
229  * Writes will be buffered until the next read or flush.
230  */
231 svn_error_t *
233  apr_pool_t *pool,
234  const svn_string_t *str);
235 
236 /** Write a cstring over the net.
237  *
238  * Writes will be buffered until the next read or flush.
239  */
240 svn_error_t *
242  apr_pool_t *pool,
243  const char *s);
244 
245 /** Write a word over the net.
246  *
247  * Writes will be buffered until the next read or flush.
248  */
249 svn_error_t *
251  apr_pool_t *pool,
252  const char *word);
253 
254 /** Write a list of properties over the net. @a props is allowed to be NULL,
255  * in which case an empty list will be written out.
256  *
257  * @since New in 1.5.
258  */
259 svn_error_t *
261  apr_pool_t *pool,
262  apr_hash_t *props);
263 
264 /** Begin a list. Writes will be buffered until the next read or flush. */
265 svn_error_t *
267  apr_pool_t *pool);
268 
269 /** End a list. Writes will be buffered until the next read or flush. */
270 svn_error_t *
272  apr_pool_t *pool);
273 
274 /** Flush the write buffer.
275  *
276  * Normally this shouldn't be necessary, since the write buffer is flushed
277  * when a read is attempted.
278  */
279 svn_error_t *
281  apr_pool_t *pool);
282 
283 /** Write a tuple, using a printf-like interface.
284  *
285  * The format string @a fmt may contain:
286  *
287  *@verbatim
288  Spec Argument type Item type
289  ---- -------------------- ---------
290  n apr_uint64_t Number
291  r svn_revnum_t Number
292  s const svn_string_t * String
293  c const char * String
294  w const char * Word
295  b svn_boolean_t Word ("true" or "false")
296  ( Begin tuple
297  ) End tuple
298  ? Remaining elements optional
299  ! (at beginning or end) Suppress opening or closing of tuple
300  @endverbatim
301  *
302  * Inside the optional part of a tuple, 'r' values may be @c
303  * SVN_INVALID_REVNUM, 'n' values may be
304  * SVN_RA_SVN_UNSPECIFIED_NUMBER, and 's', 'c', and 'w' values may be
305  * @c NULL; in these cases no data will be written. 'b' and '(' may
306  * not appear in the optional part of a tuple. Either all or none of
307  * the optional values should be valid.
308  *
309  * (If we ever have a need for an optional boolean value, we should
310  * invent a 'B' specifier which stores a boolean into an int, using -1
311  * for unspecified. Right now there is no need for such a thing.)
312  *
313  * Use the '!' format specifier to write partial tuples when you have
314  * to transmit an array or other unusual data. For example, to write
315  * a tuple containing a revision, an array of words, and a boolean:
316  * @code
317  SVN_ERR(svn_ra_svn_write_tuple(conn, pool, "r(!", rev));
318  for (i = 0; i < n; i++)
319  SVN_ERR(svn_ra_svn_write_word(conn, pool, words[i]));
320  SVN_ERR(svn_ra_svn_write_tuple(conn, pool, "!)b", flag)); @endcode
321  */
322 svn_error_t *
324  apr_pool_t *pool,
325  const char *fmt, ...);
326 
327 /** Read an item from the network into @a *item. */
328 svn_error_t *
330  apr_pool_t *pool,
331  svn_ra_svn_item_t **item);
332 
333 /** Scan data on @a conn until we find something which looks like the
334  * beginning of an svn server greeting (an open paren followed by a
335  * whitespace character). This function is appropriate for beginning
336  * a client connection opened in tunnel mode, since people's dotfiles
337  * sometimes write output to stdout. It may only be called at the
338  * beginning of a client connection.
339  */
340 svn_error_t *
342  apr_pool_t *pool);
343 
344 /** Parse an array of @c svn_sort__item_t structures as a tuple, using a
345  * printf-like interface. The format string @a fmt may contain:
346  *
347  *@verbatim
348  Spec Argument type Item type
349  ---- -------------------- ---------
350  n apr_uint64_t * Number
351  r svn_revnum_t * Number
352  s svn_string_t ** String
353  c const char ** String
354  w const char ** Word
355  b svn_boolean_t * Word ("true" or "false")
356  B apr_uint64_t * Word ("true" or "false")
357  l apr_array_header_t ** List
358  ( Begin tuple
359  ) End tuple
360  ? Tuple is allowed to end here
361  @endverbatim
362  *
363  * Note that a tuple is only allowed to end precisely at a '?', or at
364  * the end of the specification. So if @a fmt is "c?cc" and @a list
365  * contains two elements, an error will result.
366  *
367  * 'B' is similar to 'b', but may be used in the optional tuple specification.
368  * It returns TRUE, FALSE, or SVN_RA_SVN_UNSPECIFIED_NUMBER.
369  *
370  * If an optional part of a tuple contains no data, 'r' values will be
371  * set to @c SVN_INVALID_REVNUM, 'n' and 'B' values will be set to
372  * SVN_RA_SVN_UNSPECIFIED_NUMBER, and 's', 'c', 'w', and 'l' values
373  * will be set to @c NULL. 'b' may not appear inside an optional
374  * tuple specification; use 'B' instead.
375  */
376 svn_error_t *
377 svn_ra_svn_parse_tuple(const apr_array_header_t *list,
378  apr_pool_t *pool,
379  const char *fmt, ...);
380 
381 /** Read a tuple from the network and parse it as a tuple, using the
382  * format string notation from svn_ra_svn_parse_tuple().
383  */
384 svn_error_t *
386  apr_pool_t *pool,
387  const char *fmt, ...);
388 
389 /** Parse an array of @c svn_ra_svn_item_t structures as a list of
390  * properties, storing the properties in a hash table.
391  *
392  * @since New in 1.5.
393  */
394 svn_error_t *
395 svn_ra_svn_parse_proplist(const apr_array_header_t *list,
396  apr_pool_t *pool,
397  apr_hash_t **props);
398 
399 /** Read a command response from the network and parse it as a tuple, using
400  * the format string notation from svn_ra_svn_parse_tuple().
401  */
402 svn_error_t *
404  apr_pool_t *pool,
405  const char *fmt, ...);
406 
407 /** Accept commands over the network and handle them according to @a
408  * commands. Command handlers will be passed @a conn, a subpool of @a
409  * pool (cleared after each command is handled), the parameters of the
410  * command, and @a baton. Commands will be accepted until a
411  * terminating command is received (a command with "terminate" set in
412  * the command table). If a command handler returns an error wrapped
413  * in SVN_RA_SVN_CMD_ERR (see the @c SVN_CMD_ERR macro), the error
414  * will be reported to the other side of the connection and the
415  * command loop will continue; any other kind of error (typically a
416  * network or protocol error) is passed through to the caller.
417  *
418  * @since New in 1.6.
419  *
420  */
421 svn_error_t *
423  apr_pool_t *pool,
424  const svn_ra_svn_cmd_entry_t *commands,
425  void *baton,
426  svn_boolean_t error_on_disconnect);
427 
428 /** Similar to svn_ra_svn_handle_commands2 but @a error_on_disconnect
429  * is always @c FALSE.
430  *
431  * @deprecated Provided for backward compatibility with the 1.5 API.
432  */
434 svn_error_t *
436  apr_pool_t *pool,
437  const svn_ra_svn_cmd_entry_t *commands,
438  void *baton);
439 
440 /** Write a command over the network, using the same format string notation
441  * as svn_ra_svn_write_tuple().
442  */
443 svn_error_t *
445  apr_pool_t *pool,
446  const char *cmdname,
447  const char *fmt, ...);
448 
449 /** Write a successful command response over the network, using the
450  * same format string notation as svn_ra_svn_write_tuple(). Do not use
451  * partial tuples with this function; if you need to use partial
452  * tuples, just write out the "success" and argument tuple by hand.
453  */
454 svn_error_t *
456  apr_pool_t *pool,
457  const char *fmt, ...);
458 
459 /** Write an unsuccessful command response over the network. */
460 svn_error_t *
462  apr_pool_t *pool,
463  svn_error_t *err);
464 
465 /** Set @a *editor and @a *edit_baton to an editor which will pass editing
466  * operations over the network, using @a conn and @a pool.
467  *
468  * Upon successful completion of the edit, the editor will invoke @a callback
469  * with @a callback_baton as an argument.
470  */
471 void
473  void **edit_baton,
474  svn_ra_svn_conn_t *conn,
475  apr_pool_t *pool,
476  svn_ra_svn_edit_callback callback,
477  void *callback_baton);
478 
479 /** Receive edit commands over the network and use them to drive @a editor
480  * with @a edit_baton. On return, @a *aborted will be set if the edit was
481  * aborted. The drive can be terminated with a finish-replay command only
482  * if @a for_replay is TRUE.
483  */
484 svn_error_t *
486  apr_pool_t *pool,
487  const svn_delta_editor_t *editor,
488  void *edit_baton,
489  svn_boolean_t *aborted,
490  svn_boolean_t for_replay);
491 
492 /** Like svn_ra_svn_drive_editor2, but with @a for_replay always FALSE.
493  */
494 svn_error_t *
496  apr_pool_t *pool,
497  const svn_delta_editor_t *editor,
498  void *edit_baton,
499  svn_boolean_t *aborted);
500 
501 /** This function is only intended for use by svnserve.
502  *
503  * Perform CRAM-MD5 password authentication. On success, return
504  * SVN_NO_ERROR with *user set to the username and *success set to
505  * TRUE. On an error which can be reported to the client, report the
506  * error and return SVN_NO_ERROR with *success set to FALSE. On
507  * communications failure, return an error.
508  */
509 svn_error_t *
511  apr_pool_t *pool,
512  svn_config_t *pwdb,
513  const char **user,
514  svn_boolean_t *success);
515 
516 /**
517  * Get libsvn_ra_svn version information.
518  * @since New in 1.1.
519  */
520 const svn_version_t *
521 svn_ra_svn_version(void);
522 
523 #ifdef __cplusplus
524 }
525 #endif /* __cplusplus */
526 
527 #endif /* SVN_RA_SVN_H */