Subversion 1.6.16

svn_ra_svn.h

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