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 /* maps to SVN_RA_CAPABILITY_INHERITED_PROPERTIES: */
66 #define SVN_RA_SVN_CAP_INHERITED_PROPS "inherited-props"
67 /* maps to SVN_RA_CAPABILITY_EPHEMERAL_TXNPROPS */
68 #define SVN_RA_SVN_CAP_EPHEMERAL_TXNPROPS "ephemeral-txnprops"
69 /* maps to SVN_RA_CAPABILITY_GET_FILE_REVS_REVERSE */
70 #define SVN_RA_SVN_CAP_GET_FILE_REVS_REVERSE "file-revs-reverse"
71 
72 
73 /** ra_svn passes @c svn_dirent_t fields over the wire as a list of
74  * words, these are the values used to represent each field.
75  *
76  * @defgroup ra_svn_dirent_fields Definitions of ra_svn dirent fields
77  * @{
78  */
79 
80 /** The ra_svn way of saying @c SVN_DIRENT_KIND. */
81 #define SVN_RA_SVN_DIRENT_KIND "kind"
82 
83 /** The ra_svn way of saying @c SVN_DIRENT_SIZE. */
84 #define SVN_RA_SVN_DIRENT_SIZE "size"
85 
86 /** The ra_svn way of saying @c SVN_DIRENT_HAS_PROPS. */
87 #define SVN_RA_SVN_DIRENT_HAS_PROPS "has-props"
88 
89 /** The ra_svn way of saying @c SVN_DIRENT_CREATED_REV. */
90 #define SVN_RA_SVN_DIRENT_CREATED_REV "created-rev"
91 
92 /** The ra_svn way of saying @c SVN_DIRENT_TIME. */
93 #define SVN_RA_SVN_DIRENT_TIME "time"
94 
95 /** The ra_svn way of saying @c SVN_DIRENT_LAST_AUTHOR. */
96 #define SVN_RA_SVN_DIRENT_LAST_AUTHOR "last-author"
97 
98 /** @} */
99 
100 /** A value used to indicate an optional number element in a tuple that was
101  * not received.
102  */
103 #define SVN_RA_SVN_UNSPECIFIED_NUMBER ~((apr_uint64_t) 0)
104 
105 /** A specialized form of @c SVN_ERR to deal with errors which occur in an
106  * svn_ra_svn_command_handler().
107  *
108  * An error returned with this macro will be passed back to the other side
109  * of the connection. Use this macro when performing the requested operation;
110  * use the regular @c SVN_ERR when performing I/O with the client.
111  */
112 #define SVN_CMD_ERR(expr) \
113  do { \
114  svn_error_t *svn_err__temp = (expr); \
115  if (svn_err__temp) \
116  return svn_error_create(SVN_ERR_RA_SVN_CMD_ERR, \
117  svn_err__temp, NULL); \
118  } while (0)
119 
120 /** an ra_svn connection. */
121 typedef struct svn_ra_svn_conn_st svn_ra_svn_conn_t;
122 
123 /** Command handler, used by svn_ra_svn_handle_commands(). */
124 typedef svn_error_t *(*svn_ra_svn_command_handler)(svn_ra_svn_conn_t *conn,
125  apr_pool_t *pool,
126  apr_array_header_t *params,
127  void *baton);
128 
129 /** Command table, used by svn_ra_svn_handle_commands().
130  */
132 {
133  /** Name of the command */
134  const char *cmdname;
135 
136  /** Handler for the command */
138 
139  /** Termination flag. If set, command-handling will cease after
140  * command is processed. */
143 
144 /** Memory representation of an on-the-wire data item. */
145 typedef struct svn_ra_svn_item_t
146 {
147  /** Variant indicator. */
148  enum {
149  SVN_RA_SVN_NUMBER,
150  SVN_RA_SVN_STRING,
151  SVN_RA_SVN_WORD,
152  SVN_RA_SVN_LIST
153  } kind;
154  /** Variant data. */
155  union {
156  apr_uint64_t number;
157  svn_string_t *string;
158  const char *word;
159 
160  /** Contains @c svn_ra_svn_item_t's. */
161  apr_array_header_t *list;
162  } u;
164 
165 typedef svn_error_t *(*svn_ra_svn_edit_callback)(void *baton);
166 
167 /** Initialize a connection structure for the given socket or
168  * input/output streams.
169  *
170  * Either @a sock or @a in_stream/@a out_stream must be set, not both.
171  * @a compression_level specifies the desired network data compression
172  * level (zlib) from 0 (no compression) to 9 (best but slowest).
173  *
174  * If @a zero_copy_limit is not 0, cached file contents smaller than the
175  * given limit may be sent directly to the network socket. Otherwise,
176  * it will be copied into a temporary buffer before being forwarded to
177  * the network stack. Since the zero-copy code path has to enforce strict
178  * time-outs, the receiver must be able to process @a zero_copy_limit
179  * bytes within one second. Even temporary failure to do so may cause
180  * the server to cancel the respective operation with a time-out error.
181  *
182  * To reduce the overhead of checking for cancellation requests from the
183  * data receiver, set @a error_check_interval to some non-zero value.
184  * It defines the number of bytes that must have been sent since the last
185  * check before the next check will be made.
186  *
187  * @note If @a out_stream is an wrapped apr_file_t* the backing file will be
188  * used for some operations.
189  *
190  * Allocate the result in @a pool.
191  *
192  * @since New in 1.9
193  */
194 svn_ra_svn_conn_t *svn_ra_svn_create_conn4(apr_socket_t *sock,
195  svn_stream_t *in_stream,
196  svn_stream_t *out_stream,
197  int compression_level,
198  apr_size_t zero_copy_limit,
199  apr_size_t error_check_interval,
200  apr_pool_t *result_pool);
201 
202 
203 /** Similar to svn_ra_svn_create_conn4() but only supports apr_file_t handles
204  * instead of the more generic streams.
205  *
206  * @since New in 1.8
207  * @deprecated Provided for backward compatibility with the 1.8 API.
208  */
210 svn_ra_svn_conn_t *svn_ra_svn_create_conn3(apr_socket_t *sock,
211  apr_file_t *in_file,
212  apr_file_t *out_file,
213  int compression_level,
214  apr_size_t zero_copy_limit,
215  apr_size_t error_check_interval,
216  apr_pool_t *pool);
217 
218 /** Similar to svn_ra_svn_create_conn3() but disables the zero copy code
219  * path and sets the error checking interval to 0.
220  *
221  * @since New in 1.7.
222  *
223  * @deprecated Provided for backward compatibility with the 1.7 API.
224  */
227 svn_ra_svn_create_conn2(apr_socket_t *sock,
228  apr_file_t *in_file,
229  apr_file_t *out_file,
230  int compression_level,
231  apr_pool_t *pool);
232 
233 /** Similar to svn_ra_svn_create_conn2() but uses the default
234  * compression level (#SVN_DELTA_COMPRESSION_LEVEL_DEFAULT) for network
235  * transmissions.
236  *
237  * @deprecated Provided for backward compatibility with the 1.6 API.
238  */
241 svn_ra_svn_create_conn(apr_socket_t *sock,
242  apr_file_t *in_file,
243  apr_file_t *out_file,
244  apr_pool_t *pool);
245 
246 /** Add the capabilities in @a list to @a conn's capabilities.
247  * @a list contains svn_ra_svn_item_t entries (which should be of type
248  * SVN_RA_SVN_WORD; a malformed data error will result if any are not).
249  *
250  * This is idempotent: if a given capability was already set for
251  * @a conn, it remains set.
252  */
253 svn_error_t *
255  const apr_array_header_t *list);
256 
257 /** Return @c TRUE if @a conn has the capability @a capability, or
258  * @c FALSE if it does not. */
261  const char *capability);
262 
263 /** Return the data compression level to use for network transmissions.
264  *
265  * @since New in 1.7.
266  */
267 int
269 
270 /** Return the zero-copy data block limit to use for network
271  * transmissions.
272  *
273  * @see http://en.wikipedia.org/wiki/Zero-copy
274  *
275  * @since New in 1.8.
276  */
277 apr_size_t
279 
280 /** Returns the remote address of the connection as a string, if known,
281  * or NULL if inapplicable. */
282 const char *
284 
285 /** Set @a *editor and @a *edit_baton to an editor which will pass editing
286  * operations over the network, using @a conn and @a pool.
287  *
288  * Upon successful completion of the edit, the editor will invoke @a callback
289  * with @a callback_baton as an argument.
290  *
291  * @note The @c copyfrom_path parameter passed to the @c add_file and
292  * @c add_directory methods of the returned editor may be either a URL or a
293  * relative path, and is transferred verbatim to the receiving end of the
294  * connection. See svn_ra_svn_drive_editor2() for information on the
295  * receiving end of the connection.
296  */
297 void
299  void **edit_baton,
300  svn_ra_svn_conn_t *conn,
301  apr_pool_t *pool,
302  svn_ra_svn_edit_callback callback,
303  void *callback_baton);
304 
305 /** Receive edit commands over the network and use them to drive @a editor
306  * with @a edit_baton. On return, @a *aborted will be set if the edit was
307  * aborted. The drive can be terminated with a finish-replay command only
308  * if @a for_replay is TRUE.
309  *
310  * @since New in 1.4.
311  *
312  * @note The @c copyfrom_path parameter passed to the @c add_file and
313  * @c add_directory methods of the receiving editor will be canonicalized
314  * either as a URL or as a relative path (starting with a slash) according
315  * to which kind was sent by the driving end of the connection. See
316  * svn_ra_svn_get_editor() for information on the driving end of the
317  * connection.
318  */
319 svn_error_t *
321  apr_pool_t *pool,
322  const svn_delta_editor_t *editor,
323  void *edit_baton,
324  svn_boolean_t *aborted,
325  svn_boolean_t for_replay);
326 
327 /** Like svn_ra_svn_drive_editor2, but with @a for_replay always FALSE.
328  *
329  * @deprecated Provided for backward compatibility with the 1.3 API.
330  */
332 svn_error_t *
334  apr_pool_t *pool,
335  const svn_delta_editor_t *editor,
336  void *edit_baton,
337  svn_boolean_t *aborted);
338 
339 /** This function is only intended for use by svnserve.
340  *
341  * Perform CRAM-MD5 password authentication. On success, return
342  * SVN_NO_ERROR with *user set to the username and *success set to
343  * TRUE. On an error which can be reported to the client, report the
344  * error and return SVN_NO_ERROR with *success set to FALSE. On
345  * communications failure, return an error.
346  */
347 svn_error_t *
349  apr_pool_t *pool,
350  svn_config_t *pwdb,
351  const char **user,
352  svn_boolean_t *success);
353 
354 /**
355  * Get libsvn_ra_svn version information.
356  * @since New in 1.1.
357  */
358 const svn_version_t *
359 svn_ra_svn_version(void);
360 
361 /**
362  * @defgroup ra_svn_deprecated ra_svn low-level functions
363  * @{
364  */
365 
366 /** Write a number over the net.
367  *
368  * Writes will be buffered until the next read or flush.
369  *
370  * @deprecated Provided for backward compatibility with the 1.7 API.
371  * RA_SVN low-level functions are no longer considered public.
372  */
374 svn_error_t *
376  apr_pool_t *pool,
377  apr_uint64_t number);
378 
379 /** Write a string over the net.
380  *
381  * Writes will be buffered until the next read or flush.
382  *
383  * @deprecated Provided for backward compatibility with the 1.7 API.
384  * RA_SVN low-level functions are no longer considered public.
385  */
387 svn_error_t *
389  apr_pool_t *pool,
390  const svn_string_t *str);
391 
392 /** Write a cstring over the net.
393  *
394  * Writes will be buffered until the next read or flush.
395  *
396  * @deprecated Provided for backward compatibility with the 1.7 API.
397  * RA_SVN low-level functions are no longer considered public.
398  */
400 svn_error_t *
402  apr_pool_t *pool,
403  const char *s);
404 
405 /** Write a word over the net.
406  *
407  * Writes will be buffered until the next read or flush.
408  *
409  * @deprecated Provided for backward compatibility with the 1.7 API.
410  * RA_SVN low-level functions are no longer considered public.
411  */
413 svn_error_t *
415  apr_pool_t *pool,
416  const char *word);
417 
418 /** Write a list of properties over the net. @a props is allowed to be NULL,
419  * in which case an empty list will be written out.
420  *
421  * @since New in 1.5.
422  *
423  * @deprecated Provided for backward compatibility with the 1.7 API.
424  * RA_SVN low-level functions are no longer considered public.
425  */
427 svn_error_t *
429  apr_pool_t *pool,
430  apr_hash_t *props);
431 
432 /** Begin a list. Writes will be buffered until the next read or flush.
433  *
434  * @deprecated Provided for backward compatibility with the 1.7 API.
435  * RA_SVN low-level functions are no longer considered public.
436  */
438 svn_error_t *
440  apr_pool_t *pool);
441 
442 /** End a list. Writes will be buffered until the next read or flush.
443  *
444  * @deprecated Provided for backward compatibility with the 1.7 API.
445  * RA_SVN low-level functions are no longer considered public.
446  */
448 svn_error_t *
450  apr_pool_t *pool);
451 
452 /** Flush the write buffer.
453  *
454  * Normally this shouldn't be necessary, since the write buffer is flushed
455  * when a read is attempted.
456  *
457  * @deprecated Provided for backward compatibility with the 1.7 API.
458  * RA_SVN low-level functions are no longer considered public.
459  */
461 svn_error_t *
463  apr_pool_t *pool);
464 
465 /** Write a tuple, using a printf-like interface.
466  *
467  * The format string @a fmt may contain:
468  *
469  *@verbatim
470  Spec Argument type Item type
471  ---- -------------------- ---------
472  n apr_uint64_t Number
473  r svn_revnum_t Number
474  s const svn_string_t * String
475  c const char * String
476  w const char * Word
477  b svn_boolean_t Word ("true" or "false")
478  ( Begin tuple
479  ) End tuple
480  ? Remaining elements optional
481  ! (at beginning or end) Suppress opening or closing of tuple
482  @endverbatim
483  *
484  * Inside the optional part of a tuple, 'r' values may be @c
485  * SVN_INVALID_REVNUM, 'n' values may be
486  * SVN_RA_SVN_UNSPECIFIED_NUMBER, and 's', 'c', and 'w' values may be
487  * @c NULL; in these cases no data will be written. 'b' and '(' may
488  * not appear in the optional part of a tuple. Either all or none of
489  * the optional values should be valid.
490  *
491  * (If we ever have a need for an optional boolean value, we should
492  * invent a 'B' specifier which stores a boolean into an int, using -1
493  * for unspecified. Right now there is no need for such a thing.)
494  *
495  * Use the '!' format specifier to write partial tuples when you have
496  * to transmit an array or other unusual data. For example, to write
497  * a tuple containing a revision, an array of words, and a boolean:
498  * @code
499  SVN_ERR(svn_ra_svn_write_tuple(conn, pool, "r(!", rev));
500  for (i = 0; i < n; i++)
501  SVN_ERR(svn_ra_svn_write_word(conn, pool, words[i]));
502  SVN_ERR(svn_ra_svn_write_tuple(conn, pool, "!)b", flag)); @endcode
503  *
504  * @deprecated Provided for backward compatibility with the 1.7 API.
505  * RA_SVN low-level functions are no longer considered public.
506  */
508 svn_error_t *
510  apr_pool_t *pool,
511  const char *fmt, ...);
512 
513 /** Read an item from the network into @a *item.
514  *
515  * @deprecated Provided for backward compatibility with the 1.7 API.
516  * RA_SVN low-level functions are no longer considered public.
517  */
519 svn_error_t *
521  apr_pool_t *pool,
522  svn_ra_svn_item_t **item);
523 
524 /** Scan data on @a conn until we find something which looks like the
525  * beginning of an svn server greeting (an open paren followed by a
526  * whitespace character). This function is appropriate for beginning
527  * a client connection opened in tunnel mode, since people's dotfiles
528  * sometimes write output to stdout. It may only be called at the
529  * beginning of a client connection.
530  *
531  * @deprecated Provided for backward compatibility with the 1.7 API.
532  * RA_SVN low-level functions are no longer considered public.
533  */
535 svn_error_t *
537  apr_pool_t *pool);
538 
539 /** Parse an array of @c svn_sort__item_t structures as a tuple, using a
540  * printf-like interface. The format string @a fmt may contain:
541  *
542  *@verbatim
543  Spec Argument type Item type
544  ---- -------------------- ---------
545  n apr_uint64_t * Number
546  r svn_revnum_t * Number
547  s svn_string_t ** String
548  c const char ** String
549  w const char ** Word
550  b svn_boolean_t * Word ("true" or "false")
551  B apr_uint64_t * Word ("true" or "false")
552  l apr_array_header_t ** List
553  ( Begin tuple
554  ) End tuple
555  ? Tuple is allowed to end here
556  @endverbatim
557  *
558  * Note that a tuple is only allowed to end precisely at a '?', or at
559  * the end of the specification. So if @a fmt is "c?cc" and @a list
560  * contains two elements, an error will result.
561  *
562  * 'B' is similar to 'b', but may be used in the optional tuple specification.
563  * It returns TRUE, FALSE, or SVN_RA_SVN_UNSPECIFIED_NUMBER.
564  *
565  * If an optional part of a tuple contains no data, 'r' values will be
566  * set to @c SVN_INVALID_REVNUM, 'n' and 'B' values will be set to
567  * SVN_RA_SVN_UNSPECIFIED_NUMBER, and 's', 'c', 'w', and 'l' values
568  * will be set to @c NULL. 'b' may not appear inside an optional
569  * tuple specification; use 'B' instead.
570  *
571  * @deprecated Provided for backward compatibility with the 1.7 API.
572  * RA_SVN low-level functions are no longer considered public.
573  */
575 svn_error_t *
576 svn_ra_svn_parse_tuple(const apr_array_header_t *list,
577  apr_pool_t *pool,
578  const char *fmt, ...);
579 
580 /** Read a tuple from the network and parse it as a tuple, using the
581  * format string notation from svn_ra_svn_parse_tuple().
582  *
583  * @deprecated Provided for backward compatibility with the 1.7 API.
584  * RA_SVN low-level functions are no longer considered public.
585  */
587 svn_error_t *
589  apr_pool_t *pool,
590  const char *fmt, ...);
591 
592 /** Parse an array of @c svn_ra_svn_item_t structures as a list of
593  * properties, storing the properties in a hash table.
594  *
595  * @since New in 1.5.
596  *
597  * @deprecated Provided for backward compatibility with the 1.7 API.
598  * RA_SVN low-level functions are no longer considered public.
599  */
601 svn_error_t *
602 svn_ra_svn_parse_proplist(const apr_array_header_t *list,
603  apr_pool_t *pool,
604  apr_hash_t **props);
605 
606 /** Read a command response from the network and parse it as a tuple, using
607  * the format string notation from svn_ra_svn_parse_tuple().
608  *
609  * @deprecated Provided for backward compatibility with the 1.7 API.
610  * RA_SVN low-level functions are no longer considered public.
611  */
613 svn_error_t *
615  apr_pool_t *pool,
616  const char *fmt, ...);
617 
618 /** Accept commands over the network and handle them according to @a
619  * commands. Command handlers will be passed @a conn, a subpool of @a
620  * pool (cleared after each command is handled), the parameters of the
621  * command, and @a baton. Commands will be accepted until a
622  * terminating command is received (a command with "terminate" set in
623  * the command table). If a command handler returns an error wrapped
624  * in SVN_RA_SVN_CMD_ERR (see the @c SVN_CMD_ERR macro), the error
625  * will be reported to the other side of the connection and the
626  * command loop will continue; any other kind of error (typically a
627  * network or protocol error) is passed through to the caller.
628  *
629  * @since New in 1.6.
630  *
631  * @deprecated Provided for backward compatibility with the 1.7 API.
632  * RA_SVN low-level functions are no longer considered public.
633  */
635 svn_error_t *
637  apr_pool_t *pool,
638  const svn_ra_svn_cmd_entry_t *commands,
639  void *baton,
640  svn_boolean_t error_on_disconnect);
641 
642 /** Similar to svn_ra_svn_handle_commands2 but @a error_on_disconnect
643  * is always @c FALSE.
644  *
645  * @deprecated Provided for backward compatibility with the 1.5 API.
646  */
648 svn_error_t *
650  apr_pool_t *pool,
651  const svn_ra_svn_cmd_entry_t *commands,
652  void *baton);
653 
654 /** Write a command over the network, using the same format string notation
655  * as svn_ra_svn_write_tuple().
656  *
657  * @deprecated Provided for backward compatibility with the 1.7 API.
658  * RA_SVN low-level functions are no longer considered public.
659  */
661 svn_error_t *
663  apr_pool_t *pool,
664  const char *cmdname,
665  const char *fmt, ...);
666 
667 /** Write a successful command response over the network, using the
668  * same format string notation as svn_ra_svn_write_tuple(). Do not use
669  * partial tuples with this function; if you need to use partial
670  * tuples, just write out the "success" and argument tuple by hand.
671  *
672  * @deprecated Provided for backward compatibility with the 1.7 API.
673  * RA_SVN low-level functions are no longer considered public.
674  */
676 svn_error_t *
678  apr_pool_t *pool,
679  const char *fmt, ...);
680 
681 /** Write an unsuccessful command response over the network.
682  *
683  * @deprecated Provided for backward compatibility with the 1.7 API.
684  * RA_SVN low-level functions are no longer considered public.
685  */
687 svn_error_t *
689  apr_pool_t *pool,
690  svn_error_t *err);
691 
692 /**
693  * @}
694  */
695 
696 #ifdef __cplusplus
697 }
698 #endif /* __cplusplus */
699 
700 #endif /* SVN_RA_SVN_H */