- Main Page
- Related Pages
- Modules
- Data Structures
- Files

- File List
- Globals

# svn_ra_svn.h

Go to the documentation of this file.

    00001 /**
    00002  * @copyright
    00003  * ====================================================================
    00004  *    Licensed to the Apache Software Foundation (ASF) under one
    00005  *    or more contributor license agreements.  See the NOTICE file
    00006  *    distributed with this work for additional information
    00007  *    regarding copyright ownership.  The ASF licenses this file
    00008  *    to you under the Apache License, Version 2.0 (the
    00009  *    "License"); you may not use this file except in compliance
    00010  *    with the License.  You may obtain a copy of the License at
    00011  *
    00012  *      http://www.apache.org/licenses/LICENSE-2.0
    00013  *
    00014  *    Unless required by applicable law or agreed to in writing,
    00015  *    software distributed under the License is distributed on an
    00016  *    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    00017  *    KIND, either express or implied.  See the License for the
    00018  *    specific language governing permissions and limitations
    00019  *    under the License.
    00020  * ====================================================================
    00021  * @endcopyright
    00022  *
    00023  * @file svn_ra_svn.h
    00024  * @brief libsvn_ra_svn functions used by the server
    00025  */
    00026
    00027 #ifndef SVN_RA_SVN_H
    00028 #define SVN_RA_SVN_H
    00029
    00030 #include <apr.h>
    00031 #include <apr_pools.h>
    00032 #include <apr_hash.h>
    00033 #include <apr_tables.h>
    00034 #include <apr_file_io.h>     /* for apr_file_t */
    00035 #include <apr_network_io.h>  /* for apr_socket_t */
    00036
    00037 #include "svn_types.h"
    00038 #include "svn_string.h"
    00039 #include "svn_config.h"
    00040 #include "svn_delta.h"
    00041
    00042 #ifdef __cplusplus
    00043 extern "C" {
    00044 #endif /* __cplusplus */
    00045
    00046 /** The well-known svn port number. */
    00047 #define SVN_RA_SVN_PORT 3690
    00048
    00049 /** Currently-defined capabilities. */
    00050 #define SVN_RA_SVN_CAP_EDIT_PIPELINE "edit-pipeline"
    00051 #define SVN_RA_SVN_CAP_SVNDIFF1 "svndiff1"
    00052 #define SVN_RA_SVN_CAP_ABSENT_ENTRIES "absent-entries"
    00053 /* maps to SVN_RA_CAPABILITY_COMMIT_REVPROPS: */
    00054 #define SVN_RA_SVN_CAP_COMMIT_REVPROPS "commit-revprops"
    00055 /* maps to SVN_RA_CAPABILITY_MERGEINFO: */
    00056 #define SVN_RA_SVN_CAP_MERGEINFO "mergeinfo"
    00057 /* maps to SVN_RA_CAPABILITY_DEPTH: */
    00058 #define SVN_RA_SVN_CAP_DEPTH "depth"
    00059 /* maps to SVN_RA_CAPABILITY_LOG_REVPROPS */
    00060 #define SVN_RA_SVN_CAP_LOG_REVPROPS "log-revprops"
    00061 /* maps to SVN_RA_CAPABILITY_PARTIAL_REPLAY */
    00062 #define SVN_RA_SVN_CAP_PARTIAL_REPLAY "partial-replay"
    00063 /* maps to SVN_RA_CAPABILITY_ATOMIC_REVPROPS */
    00064 #define SVN_RA_SVN_CAP_ATOMIC_REVPROPS "atomic-revprops"
    00065
    00066 /** ra_svn passes @c svn_dirent_t fields over the wire as a list of
    00067  * words, these are the values used to represent each field.
    00068  *
    00069  * @defgroup ra_svn_dirent_fields Definitions of ra_svn dirent fields
    00070  * @{
    00071  */
    00072
    00073 /** The ra_svn way of saying @c SVN_DIRENT_KIND. */
    00074 #define SVN_RA_SVN_DIRENT_KIND "kind"
    00075
    00076 /** The ra_svn way of saying @c SVN_DIRENT_SIZE. */
    00077 #define SVN_RA_SVN_DIRENT_SIZE "size"
    00078
    00079 /** The ra_svn way of saying @c SVN_DIRENT_HAS_PROPS. */
    00080 #define SVN_RA_SVN_DIRENT_HAS_PROPS "has-props"
    00081
    00082 /** The ra_svn way of saying @c SVN_DIRENT_CREATED_REV. */
    00083 #define SVN_RA_SVN_DIRENT_CREATED_REV "created-rev"
    00084
    00085 /** The ra_svn way of saying @c SVN_DIRENT_TIME. */
    00086 #define SVN_RA_SVN_DIRENT_TIME "time"
    00087
    00088 /** The ra_svn way of saying @c SVN_DIRENT_LAST_AUTHOR. */
    00089 #define SVN_RA_SVN_DIRENT_LAST_AUTHOR "last-author"
    00090
    00091 /** @} */
    00092
    00093 /** A value used to indicate an optional number element in a tuple that was
    00094  * not received.
    00095  */
    00096 #define SVN_RA_SVN_UNSPECIFIED_NUMBER ~((apr_uint64_t) 0)
    00097
    00098 /** A specialized form of @c SVN_ERR to deal with errors which occur in an
    00099  * svn_ra_svn_command_handler().
    00100  *
    00101  * An error returned with this macro will be passed back to the other side
    00102  * of the connection.  Use this macro when performing the requested operation;
    00103  * use the regular @c SVN_ERR when performing I/O with the client.
    00104  */
    00105 #define SVN_CMD_ERR(expr)                                     \
    00106   do {                                                        \
    00107     svn_error_t *svn_err__temp = (expr);                      \
    00108     if (svn_err__temp)                                        \
    00109       return svn_error_create(SVN_ERR_RA_SVN_CMD_ERR,         \
    00110                               svn_err__temp, NULL);           \
    00111   } while (0)
    00112
    00113 /** an ra_svn connection. */
    00114 typedef struct svn_ra_svn_conn_st svn_ra_svn_conn_t;
    00115
    00116 /** Command handler, used by svn_ra_svn_handle_commands(). */
    00117 typedef svn_error_t *(*svn_ra_svn_command_handler)(svn_ra_svn_conn_t *conn,
    00118                                                    apr_pool_t *pool,
    00119                                                    apr_array_header_t *params,
    00120                                                    void *baton);
    00121
    00122 /** Command table, used by svn_ra_svn_handle_commands().
    00123  */
    00124 typedef struct svn_ra_svn_cmd_entry_t
    00125 {
    00126   /** Name of the command */
    00127   const char *cmdname;
    00128
    00129   /** Handler for the command */
    00130   svn_ra_svn_command_handler handler;
    00131
    00132   /** Termination flag.  If set, command-handling will cease after
    00133    * command is processed. */
    00134   svn_boolean_t terminate;
    00135 } svn_ra_svn_cmd_entry_t;
    00136
    00137 /** Memory representation of an on-the-wire data item. */
    00138 typedef struct svn_ra_svn_item_t
    00139 {
    00140   /** Variant indicator. */
    00141   enum {
    00142     SVN_RA_SVN_NUMBER,
    00143     SVN_RA_SVN_STRING,
    00144     SVN_RA_SVN_WORD,
    00145     SVN_RA_SVN_LIST
    00146   } kind;
    00147   /** Variant data. */
    00148   union {
    00149     apr_uint64_t number;
    00150     svn_string_t *string;
    00151     const char *word;
    00152
    00153     /** Contains @c svn_ra_svn_item_t's. */
    00154     apr_array_header_t *list;
    00155   } u;
    00156 } svn_ra_svn_item_t;
    00157
    00158 typedef svn_error_t *(*svn_ra_svn_edit_callback)(void *baton);
    00159
    00160 /** Initialize a connection structure for the given socket or
    00161  * input/output files.
    00162  *
    00163  * Either @a sock or @a in_file/@a out_file must be set, not both.
    00164  * Specify the desired network data compression level (zlib) from
    00165  * 0 (no compression) to 9 (best but slowest).
    00166  *
    00167  * @since New in 1.7.
    00168  */
    00169 svn_ra_svn_conn_t *
    00170 svn_ra_svn_create_conn2(apr_socket_t *sock,
    00171                         apr_file_t *in_file,
    00172                         apr_file_t *out_file,
    00173                         int compression_level,
    00174                         apr_pool_t *pool);
    00175
    00176 /** Similar to svn_ra_svn_create_conn2() but uses default
    00177  * compression level (#SVN_DELTA_COMPRESSION_LEVEL_DEFAULT) for network
    00178  * transmissions.
    00179  *
    00180  * @deprecated Provided for backward compatibility with the 1.6 API.
    00181  */
    00182 SVN_DEPRECATED
    00183 svn_ra_svn_conn_t *
    00184 svn_ra_svn_create_conn(apr_socket_t *sock,
    00185                        apr_file_t *in_file,
    00186                        apr_file_t *out_file,
    00187                        apr_pool_t *pool);
    00188
    00189 /** Add the capabilities in @a list to @a conn's capabilities.
    00190  * @a list contains svn_ra_svn_item_t entries (which should be of type
    00191  * SVN_RA_SVN_WORD; a malformed data error will result if any are not).
    00192  *
    00193  * This is idempotent: if a given capability was already set for
    00194  * @a conn, it remains set.
    00195  */
    00196 svn_error_t *
    00197 svn_ra_svn_set_capabilities(svn_ra_svn_conn_t *conn,
    00198                             const apr_array_header_t *list);
    00199
    00200 /** Return @c TRUE if @a conn has the capability @a capability, or
    00201  * @c FALSE if it does not. */
    00202 svn_boolean_t
    00203 svn_ra_svn_has_capability(svn_ra_svn_conn_t *conn,
    00204                           const char *capability);
    00205
    00206 /** Return the data compression level to use for network transmissions
    00207  *
    00208  * @since New in 1.7.
    00209  */
    00210 int
    00211 svn_ra_svn_compression_level(svn_ra_svn_conn_t *conn);
    00212
    00213 /** Returns the remote address of the connection as a string, if known,
    00214  *  or NULL if inapplicable. */
    00215 const char *
    00216 svn_ra_svn_conn_remote_host(svn_ra_svn_conn_t *conn);
    00217
    00218 /** Write a number over the net.
    00219  *
    00220  * Writes will be buffered until the next read or flush.
    00221  */
    00222 svn_error_t *
    00223 svn_ra_svn_write_number(svn_ra_svn_conn_t *conn,
    00224                         apr_pool_t *pool,
    00225                         apr_uint64_t number);
    00226
    00227 /** Write a string over the net.
    00228  *
    00229  * Writes will be buffered until the next read or flush.
    00230  */
    00231 svn_error_t *
    00232 svn_ra_svn_write_string(svn_ra_svn_conn_t *conn,
    00233                         apr_pool_t *pool,
    00234                         const svn_string_t *str);
    00235
    00236 /** Write a cstring over the net.
    00237  *
    00238  * Writes will be buffered until the next read or flush.
    00239  */
    00240 svn_error_t *
    00241 svn_ra_svn_write_cstring(svn_ra_svn_conn_t *conn,
    00242                          apr_pool_t *pool,
    00243                          const char *s);
    00244
    00245 /** Write a word over the net.
    00246  *
    00247  * Writes will be buffered until the next read or flush.
    00248  */
    00249 svn_error_t *
    00250 svn_ra_svn_write_word(svn_ra_svn_conn_t *conn,
    00251                       apr_pool_t *pool,
    00252                       const char *word);
    00253
    00254 /** Write a list of properties over the net.  @a props is allowed to be NULL,
    00255  * in which case an empty list will be written out.
    00256  *
    00257  * @since New in 1.5.
    00258  */
    00259 svn_error_t *
    00260 svn_ra_svn_write_proplist(svn_ra_svn_conn_t *conn,
    00261                           apr_pool_t *pool,
    00262                           apr_hash_t *props);
    00263
    00264 /** Begin a list.  Writes will be buffered until the next read or flush. */
    00265 svn_error_t *
    00266 svn_ra_svn_start_list(svn_ra_svn_conn_t *conn,
    00267                       apr_pool_t *pool);
    00268
    00269 /** End a list.  Writes will be buffered until the next read or flush. */
    00270 svn_error_t *
    00271 svn_ra_svn_end_list(svn_ra_svn_conn_t *conn,
    00272                     apr_pool_t *pool);
    00273
    00274 /** Flush the write buffer.
    00275  *
    00276  * Normally this shouldn't be necessary, since the write buffer is flushed
    00277  * when a read is attempted.
    00278  */
    00279 svn_error_t *
    00280 svn_ra_svn_flush(svn_ra_svn_conn_t *conn,
    00281                  apr_pool_t *pool);
    00282
    00283 /** Write a tuple, using a printf-like interface.
    00284  *
    00285  * The format string @a fmt may contain:
    00286  *
    00287  *@verbatim
    00288      Spec  Argument type         Item type
    00289      ----  --------------------  ---------
    00290      n     apr_uint64_t          Number
    00291      r     svn_revnum_t          Number
    00292      s     const svn_string_t *  String
    00293      c     const char *          String
    00294      w     const char *          Word
    00295      b     svn_boolean_t         Word ("true" or "false")
    00296      (                           Begin tuple
    00297      )                           End tuple
    00298      ?                           Remaining elements optional
    00299      ! (at beginning or end)     Suppress opening or closing of tuple
    00300   @endverbatim
    00301  *
    00302  * Inside the optional part of a tuple, 'r' values may be @c
    00303  * SVN_INVALID_REVNUM, 'n' values may be
    00304  * SVN_RA_SVN_UNSPECIFIED_NUMBER, and 's', 'c', and 'w' values may be
    00305  * @c NULL; in these cases no data will be written.  'b' and '(' may
    00306  * not appear in the optional part of a tuple.  Either all or none of
    00307  * the optional values should be valid.
    00308  *
    00309  * (If we ever have a need for an optional boolean value, we should
    00310  * invent a 'B' specifier which stores a boolean into an int, using -1
    00311  * for unspecified.  Right now there is no need for such a thing.)
    00312  *
    00313  * Use the '!' format specifier to write partial tuples when you have
    00314  * to transmit an array or other unusual data.  For example, to write
    00315  * a tuple containing a revision, an array of words, and a boolean:
    00316  * @code
    00317      SVN_ERR(svn_ra_svn_write_tuple(conn, pool, "r(!", rev));
    00318      for (i = 0; i < n; i++)
    00319        SVN_ERR(svn_ra_svn_write_word(conn, pool, words[i]));
    00320      SVN_ERR(svn_ra_svn_write_tuple(conn, pool, "!)b", flag)); @endcode
    00321  */
    00322 svn_error_t *
    00323 svn_ra_svn_write_tuple(svn_ra_svn_conn_t *conn,
    00324                        apr_pool_t *pool,
    00325                        const char *fmt, ...);
    00326
    00327 /** Read an item from the network into @a *item. */
    00328 svn_error_t *
    00329 svn_ra_svn_read_item(svn_ra_svn_conn_t *conn,
    00330                      apr_pool_t *pool,
    00331                      svn_ra_svn_item_t **item);
    00332
    00333 /** Scan data on @a conn until we find something which looks like the
    00334  * beginning of an svn server greeting (an open paren followed by a
    00335  * whitespace character).  This function is appropriate for beginning
    00336  * a client connection opened in tunnel mode, since people's dotfiles
    00337  * sometimes write output to stdout.  It may only be called at the
    00338  * beginning of a client connection.
    00339  */
    00340 svn_error_t *
    00341 svn_ra_svn_skip_leading_garbage(svn_ra_svn_conn_t *conn,
    00342                                 apr_pool_t *pool);
    00343
    00344 /** Parse an array of @c svn_sort__item_t structures as a tuple, using a
    00345  * printf-like interface.  The format string @a fmt may contain:
    00346  *
    00347  *@verbatim
    00348      Spec  Argument type          Item type
    00349      ----  --------------------   ---------
    00350      n     apr_uint64_t *         Number
    00351      r     svn_revnum_t *         Number
    00352      s     svn_string_t **        String
    00353      c     const char **          String
    00354      w     const char **          Word
    00355      b     svn_boolean_t *        Word ("true" or "false")
    00356      B     apr_uint64_t *         Word ("true" or "false")
    00357      l     apr_array_header_t **  List
    00358      (                            Begin tuple
    00359      )                            End tuple
    00360      ?                            Tuple is allowed to end here
    00361   @endverbatim
    00362  *
    00363  * Note that a tuple is only allowed to end precisely at a '?', or at
    00364  * the end of the specification.  So if @a fmt is "c?cc" and @a list
    00365  * contains two elements, an error will result.
    00366  *
    00367  * 'B' is similar to 'b', but may be used in the optional tuple specification.
    00368  * It returns TRUE, FALSE, or SVN_RA_SVN_UNSPECIFIED_NUMBER.
    00369  *
    00370  * If an optional part of a tuple contains no data, 'r' values will be
    00371  * set to @c SVN_INVALID_REVNUM, 'n' and 'B' values will be set to
    00372  * SVN_RA_SVN_UNSPECIFIED_NUMBER, and 's', 'c', 'w', and 'l' values
    00373  * will be set to @c NULL.  'b' may not appear inside an optional
    00374  * tuple specification; use 'B' instead.
    00375  */
    00376 svn_error_t *
    00377 svn_ra_svn_parse_tuple(const apr_array_header_t *list,
    00378                        apr_pool_t *pool,
    00379                        const char *fmt, ...);
    00380
    00381 /** Read a tuple from the network and parse it as a tuple, using the
    00382  * format string notation from svn_ra_svn_parse_tuple().
    00383  */
    00384 svn_error_t *
    00385 svn_ra_svn_read_tuple(svn_ra_svn_conn_t *conn,
    00386                       apr_pool_t *pool,
    00387                       const char *fmt, ...);
    00388
    00389 /** Parse an array of @c svn_ra_svn_item_t structures as a list of
    00390  * properties, storing the properties in a hash table.
    00391  *
    00392  * @since New in 1.5.
    00393  */
    00394 svn_error_t *
    00395 svn_ra_svn_parse_proplist(const apr_array_header_t *list,
    00396                           apr_pool_t *pool,
    00397                           apr_hash_t **props);
    00398
    00399 /** Read a command response from the network and parse it as a tuple, using
    00400  * the format string notation from svn_ra_svn_parse_tuple().
    00401  */
    00402 svn_error_t *
    00403 svn_ra_svn_read_cmd_response(svn_ra_svn_conn_t *conn,
    00404                              apr_pool_t *pool,
    00405                              const char *fmt, ...);
    00406
    00407 /** Accept commands over the network and handle them according to @a
    00408  * commands.  Command handlers will be passed @a conn, a subpool of @a
    00409  * pool (cleared after each command is handled), the parameters of the
    00410  * command, and @a baton.  Commands will be accepted until a
    00411  * terminating command is received (a command with "terminate" set in
    00412  * the command table).  If a command handler returns an error wrapped
    00413  * in SVN_RA_SVN_CMD_ERR (see the @c SVN_CMD_ERR macro), the error
    00414  * will be reported to the other side of the connection and the
    00415  * command loop will continue; any other kind of error (typically a
    00416  * network or protocol error) is passed through to the caller.
    00417  *
    00418  * @since New in 1.6.
    00419  *
    00420  */
    00421 svn_error_t *
    00422 svn_ra_svn_handle_commands2(svn_ra_svn_conn_t *conn,
    00423                             apr_pool_t *pool,
    00424                             const svn_ra_svn_cmd_entry_t *commands,
    00425                             void *baton,
    00426                             svn_boolean_t error_on_disconnect);
    00427
    00428 /** Similar to svn_ra_svn_handle_commands2 but @a error_on_disconnect
    00429  * is always @c FALSE.
    00430  *
    00431  * @deprecated Provided for backward compatibility with the 1.5 API.
    00432  */
    00433 SVN_DEPRECATED
    00434 svn_error_t *
    00435 svn_ra_svn_handle_commands(svn_ra_svn_conn_t *conn,
    00436                            apr_pool_t *pool,
    00437                            const svn_ra_svn_cmd_entry_t *commands,
    00438                            void *baton);
    00439
    00440 /** Write a command over the network, using the same format string notation
    00441  * as svn_ra_svn_write_tuple().
    00442  */
    00443 svn_error_t *
    00444 svn_ra_svn_write_cmd(svn_ra_svn_conn_t *conn,
    00445                      apr_pool_t *pool,
    00446                      const char *cmdname,
    00447                      const char *fmt, ...);
    00448
    00449 /** Write a successful command response over the network, using the
    00450  * same format string notation as svn_ra_svn_write_tuple().  Do not use
    00451  * partial tuples with this function; if you need to use partial
    00452  * tuples, just write out the "success" and argument tuple by hand.
    00453  */
    00454 svn_error_t *
    00455 svn_ra_svn_write_cmd_response(svn_ra_svn_conn_t *conn,
    00456                               apr_pool_t *pool,
    00457                               const char *fmt, ...);
    00458
    00459 /** Write an unsuccessful command response over the network. */
    00460 svn_error_t *
    00461 svn_ra_svn_write_cmd_failure(svn_ra_svn_conn_t *conn,
    00462                              apr_pool_t *pool,
    00463                              svn_error_t *err);
    00464
    00465 /** Set @a *editor and @a *edit_baton to an editor which will pass editing
    00466  * operations over the network, using @a conn and @a pool.
    00467  *
    00468  * Upon successful completion of the edit, the editor will invoke @a callback
    00469  * with @a callback_baton as an argument.
    00470  */
    00471 void
    00472 svn_ra_svn_get_editor(const svn_delta_editor_t **editor,
    00473                       void **edit_baton,
    00474                       svn_ra_svn_conn_t *conn,
    00475                       apr_pool_t *pool,
    00476                       svn_ra_svn_edit_callback callback,
    00477                       void *callback_baton);
    00478
    00479 /** Receive edit commands over the network and use them to drive @a editor
    00480  * with @a edit_baton.  On return, @a *aborted will be set if the edit was
    00481  * aborted.  The drive can be terminated with a finish-replay command only
    00482  * if @a for_replay is TRUE.
    00483  */
    00484 svn_error_t *
    00485 svn_ra_svn_drive_editor2(svn_ra_svn_conn_t *conn,
    00486                          apr_pool_t *pool,
    00487                          const svn_delta_editor_t *editor,
    00488                          void *edit_baton,
    00489                          svn_boolean_t *aborted,
    00490                          svn_boolean_t for_replay);
    00491
    00492 /** Like svn_ra_svn_drive_editor2, but with @a for_replay always FALSE.
    00493  */
    00494 svn_error_t *
    00495 svn_ra_svn_drive_editor(svn_ra_svn_conn_t *conn,
    00496                         apr_pool_t *pool,
    00497                         const svn_delta_editor_t *editor,
    00498                         void *edit_baton,
    00499                         svn_boolean_t *aborted);
    00500
    00501 /** This function is only intended for use by svnserve.
    00502  *
    00503  * Perform CRAM-MD5 password authentication.  On success, return
    00504  * SVN_NO_ERROR with *user set to the username and *success set to
    00505  * TRUE.  On an error which can be reported to the client, report the
    00506  * error and return SVN_NO_ERROR with *success set to FALSE.  On
    00507  * communications failure, return an error.
    00508  */
    00509 svn_error_t *
    00510 svn_ra_svn_cram_server(svn_ra_svn_conn_t *conn,
    00511                        apr_pool_t *pool,
    00512                        svn_config_t *pwdb,
    00513                        const char **user,
    00514                        svn_boolean_t *success);
    00515
    00516 /**
    00517  * Get libsvn_ra_svn version information.
    00518  * @since New in 1.1.
    00519  */
    00520 const svn_version_t *
    00521 svn_ra_svn_version(void);
    00522
    00523 #ifdef __cplusplus
    00524 }
    00525 #endif /* __cplusplus */
    00526
    00527 #endif  /* SVN_RA_SVN_H */

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines