svn_ra_svn.h

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

Generated on Sun Mar 1 17:18:33 2009 for Subversion by  doxygen 1.4.7