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