Main Page   Modules   Data Structures   File List   Data Fields   Globals  

svn_ra_svn.h

Go to the documentation of this file.
00001 /**
00002  * @copyright
00003  * ====================================================================
00004  * Copyright (c) 2000-2004 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 
00045 /** A specialized form of @c SVN_ERR to deal with errors which occur in an
00046  * @c svn_ra_svn_command_handler.
00047  *
00048  * An error returned with this macro will be passed back to the other side 
00049  * of the connection.  Use this macro when performing the requested operation; 
00050  * use the regular @c SVN_ERR when performing I/O with the client.
00051  */
00052 #define SVN_CMD_ERR(expr)                                     \
00053   do {                                                        \
00054     svn_error_t *svn_err__temp = (expr);                      \
00055     if (svn_err__temp)                                        \
00056       return svn_error_create(SVN_ERR_RA_SVN_CMD_ERR,         \
00057                               svn_err__temp, NULL);           \
00058   } while (0)
00059 
00060 /** an ra_svn connection. */
00061 typedef struct svn_ra_svn_conn_st svn_ra_svn_conn_t;
00062 
00063 /** Command handler, used by @c svn_ra_svn_handle_commands. */
00064 typedef svn_error_t *(*svn_ra_svn_command_handler)(svn_ra_svn_conn_t *conn,
00065                                                    apr_pool_t *pool,
00066                                                    apr_array_header_t *params,
00067                                                    void *baton);
00068 
00069 /** Command table, used by @c svn_ra_svn_handle_commands.
00070  *
00071  * If @c terminate is set, command-handling will cease after command is
00072  * processed.
00073  */
00074 typedef struct svn_ra_svn_cmd_entry_t 
00075 {
00076   const char *cmdname;
00077   svn_ra_svn_command_handler handler;
00078   svn_boolean_t terminate;
00079 } svn_ra_svn_cmd_entry_t;
00080 
00081 /** Memory representation of an on-the-wire data item. */
00082 typedef struct svn_ra_svn_item_t 
00083 {
00084   enum {
00085     SVN_RA_SVN_NUMBER,
00086     SVN_RA_SVN_STRING,
00087     SVN_RA_SVN_WORD,
00088     SVN_RA_SVN_LIST
00089   } kind;
00090   union {
00091     apr_uint64_t number;
00092     svn_string_t *string;
00093     const char *word;
00094 
00095     /** Contains @c svn_ra_svn_item_t's. */
00096     apr_array_header_t *list;
00097   } u;
00098 } svn_ra_svn_item_t;
00099 
00100 typedef svn_error_t *(*svn_ra_svn_edit_callback)(void *baton);
00101 
00102 /** Initialize a connection structure for the given socket or
00103  * input/output files.
00104  *
00105  * Either @c sock or @c in_file/@c out_file must be set, not both.
00106  */
00107 svn_ra_svn_conn_t *svn_ra_svn_create_conn(apr_socket_t *sock,
00108                                           apr_file_t *in_file,
00109                                           apr_file_t *out_file,
00110                                           apr_pool_t *pool);
00111 
00112 /** Initialize a connection's capabilities to the ones specified in
00113  * @a list, which contains svn_ra_svn_item_t entries (which should
00114  * be of type SVN_RA_SVN_WORD; a malformed data error will result if
00115  * any are not). */
00116 svn_error_t *svn_ra_svn_set_capabilities(svn_ra_svn_conn_t *conn,
00117                                          apr_array_header_t *list);
00118 
00119 /** Return @c TRUE if @a conn has the capability @a capability, or
00120  * @c FALSE if it does not. */
00121 svn_boolean_t svn_ra_svn_has_capability(svn_ra_svn_conn_t *conn,
00122                                         const char *capability);
00123 
00124 /** Write a number over the net.
00125  *
00126  * Writes will be buffered until the next read or flush.
00127  */
00128 svn_error_t *svn_ra_svn_write_number(svn_ra_svn_conn_t *conn, apr_pool_t *pool,
00129                                      apr_uint64_t number);
00130 
00131 /** Write a string over the net.
00132  *
00133  * Writes will be buffered until the next read or flush.
00134  */
00135 svn_error_t *svn_ra_svn_write_string(svn_ra_svn_conn_t *conn, apr_pool_t *pool,
00136                                      const svn_string_t *str);
00137 
00138 /** Write a cstring over the net.
00139  *
00140  * Writes will be buffered until the next read or flush.
00141  */
00142 svn_error_t *svn_ra_svn_write_cstring(svn_ra_svn_conn_t *conn,
00143                                       apr_pool_t *pool, const char *s);
00144 
00145 /** Write a word over the net.
00146  *
00147  * Writes will be buffered until the next read or flush.
00148  */
00149 svn_error_t *svn_ra_svn_write_word(svn_ra_svn_conn_t *conn, apr_pool_t *pool,
00150                                    const char *word);
00151 
00152 /** Begin a list.  Writes will be buffered until the next read or flush. */
00153 svn_error_t *svn_ra_svn_start_list(svn_ra_svn_conn_t *conn, apr_pool_t *pool);
00154 
00155 /** End a list.  Writes will be buffered until the next read or flush. */
00156 svn_error_t *svn_ra_svn_end_list(svn_ra_svn_conn_t *conn, apr_pool_t *pool);
00157 
00158 /** Flush the write buffer.
00159  *
00160  * Normally this shouldn't be necessary, since the write buffer is flushed
00161  * when a read is attempted.
00162  */
00163 svn_error_t *svn_ra_svn_flush(svn_ra_svn_conn_t *conn, apr_pool_t *pool);
00164 
00165 /** Write a tuple, using a printf-like interface.
00166  *
00167  * The format string @a fmt may contain:
00168  *
00169  *<pre>
00170  *   Spec  Argument type         Item type
00171  *   ----  --------------------  ---------
00172  *   n     apr_uint64_t          Number
00173  *   r     svn_revnum_t          Number
00174  *   s     const svn_string_t *  String
00175  *   c     const char *          String
00176  *   w     const char *          Word
00177  *   b     svn_boolean_t         Word ("true" or "false")
00178  *   (                           Begin tuple
00179  *   )                           End tuple
00180  *   ?                           Remaining elements optional
00181  *   ! (at beginning or end)     Suppress opening or closing of tuple
00182  * </pre>
00183  *
00184  * Inside the optional part of a tuple, 'r' values may be @c
00185  * SVN_INVALID_REVNUM and 's', 'c', and 'w' values may be @c NULL; in
00186  * these cases no data will be written.  'n', 'b', and '(' may not
00187  * appear in the optional part of a tuple.  Either all or none of the
00188  * optional values should be valid.
00189  *
00190  * Use the '!' format specifier to write partial tuples when you have
00191  * to transmit an array or other unusual data.  For example, to write
00192  * a tuple containing a revision, an array of words, and a boolean:
00193  *   SVN_ERR(svn_ra_svn_write_tuple(conn, pool, "r(!", rev));
00194  *   for (i = 0; i < n; i++)
00195  *     SVN_ERR(svn_ra_svn_write_word(conn, pool, words[i]));
00196  *   SVN_ERR(svn_ra_svn_write_tuple(conn, pool, "!)b", flag));
00197  */
00198 svn_error_t *svn_ra_svn_write_tuple(svn_ra_svn_conn_t *conn, apr_pool_t *pool,
00199                                     const char *fmt, ...);
00200 
00201 /** Read an item from the network into @c item. */
00202 svn_error_t *svn_ra_svn_read_item(svn_ra_svn_conn_t *conn, apr_pool_t *pool,
00203                                   svn_ra_svn_item_t **item);
00204 
00205 /** Scan data on @c conn until we find something which looks like the
00206  * beginning of an svn server greeting (an open paren followed by a
00207  * whitespace character).  This function is appropriate for beginning
00208  * a client connection opened in tunnel mode, since people's dotfiles
00209  * sometimes write output to stdout.  It may only be called at the
00210  * beginning of a client connection.
00211  */
00212 svn_error_t *svn_ra_svn_skip_leading_garbage(svn_ra_svn_conn_t *conn,
00213                                              apr_pool_t *pool);
00214 
00215 /** Parse an array of @c svn_sort__item_t structures as a tuple, using a
00216  * printf-like interface.  The format string @a fmt may contain:
00217  *
00218  *<pre>
00219  *   Spec  Argument type          Item type
00220  *   ----  --------------------   ---------
00221  *   n     apr_uint64_t *         Number
00222  *   r     svn_revnum_t *         Number
00223  *   s     svn_string_t **        String
00224  *   c     const char **          String
00225  *   w     const char **          Word
00226  *   b     svn_boolean_t *        Word ("true" or "false")
00227  *   l     apr_array_header_t **  List
00228  *   (                            Begin tuple
00229  *   )                            End tuple
00230  *   ?                            Tuple is allowed to end here
00231  *</pre>
00232  *
00233  * Note that a tuple is only allowed to end precisely at a '?', or at
00234  * the end of the specification, of course.  So if @a fmt is "c?cc"
00235  * and @a list contains two elements, an error will result.
00236  *
00237  * If an optional part of a tuple contains no data, 'r' values will be
00238  * set to @c SVN_INVALID_REVNUM and 's', 'c', 'w', and 'l' values will
00239  * be set to @c NULL.  'n' and 'b' may not appear inside an optional
00240  * tuple specification.
00241  */
00242 svn_error_t *svn_ra_svn_parse_tuple(apr_array_header_t *list,
00243                                     apr_pool_t *pool,
00244                                     const char *fmt, ...);
00245 
00246 /** Read a tuple from the network and parse it as a tuple, using the
00247  * format string notation from @c svn_ra_svn_parse_tuple.
00248  */
00249 svn_error_t *svn_ra_svn_read_tuple(svn_ra_svn_conn_t *conn, apr_pool_t *pool,
00250                                    const char *fmt, ...);
00251 
00252 /** Read a command response from the network and parse it as a tuple, using 
00253  * the format string notation from @c svn_ra_svn_parse_tuple.
00254  */
00255 svn_error_t *svn_ra_svn_read_cmd_response(svn_ra_svn_conn_t *conn,
00256                                           apr_pool_t *pool,
00257                                           const char *fmt, ...);
00258 
00259 /** Accept commands over the network and handle them according to @a
00260  * commands.  Command handlers will be passed @a conn, a subpool of @a
00261  * pool (cleared after each command is handled), the parameters of the
00262  * command, and @a baton.  Commands will be accepted until a
00263  * terminating command is received (a command with "terminate" set in
00264  * the command table).  If a command handler returns an errors wrapped
00265  * in SVN_RA_SVN_CMD_ERR (see the SVN_CMD_ERR macro above), the error
00266  * will be reported to the other side of the connection and the
00267  * command loop will continue; any other kind of error (typically a
00268  * network or protocol error) is passed through to the caller.
00269  */
00270 svn_error_t *svn_ra_svn_handle_commands(svn_ra_svn_conn_t *conn,
00271                                         apr_pool_t *pool,
00272                                         const svn_ra_svn_cmd_entry_t *commands,
00273                                         void *baton);
00274 
00275 /** Write a command over the network, using the same format string notation 
00276  * as svn_ra_svn_write_tuple.
00277  */
00278 svn_error_t *svn_ra_svn_write_cmd(svn_ra_svn_conn_t *conn, apr_pool_t *pool,
00279                                   const char *cmdname, const char *fmt, ...);
00280 
00281 /** Write a successful command response over the network, using the
00282  * same format string notation as svn_ra_svn_write_tuple.  Do not use
00283  * partial tuples with this function; if you need to use partial
00284  * tuples, just write out the "success" and argument tuple by hand.
00285  */
00286 svn_error_t *svn_ra_svn_write_cmd_response(svn_ra_svn_conn_t *conn,
00287                                            apr_pool_t *pool,
00288                                            const char *fmt, ...);
00289 
00290 /** Write an unsuccessful command response over the network. */
00291 svn_error_t *svn_ra_svn_write_cmd_failure(svn_ra_svn_conn_t *conn,
00292                                           apr_pool_t *pool, svn_error_t *err);
00293 
00294 /** Set @a *editor and @a *edit_baton to an editor which will pass editing
00295  * operations over the network, using @a conn and @a pool.
00296  *
00297  * Upon successful completion of the edit, the editor will invoke @a callback 
00298  * with @a callback_baton as an argument.
00299  */
00300 void svn_ra_svn_get_editor(const svn_delta_editor_t **editor,
00301                            void **edit_baton, svn_ra_svn_conn_t *conn,
00302                            apr_pool_t *pool, svn_ra_svn_edit_callback callback,
00303                            void *callback_baton);
00304 
00305 /** Receive edit commands over the network and use them to drive @a editor
00306  * with @a edit_baton.  On return, @a *aborted will be set if the edit was
00307  * aborted.
00308  */
00309 svn_error_t *svn_ra_svn_drive_editor(svn_ra_svn_conn_t *conn, apr_pool_t *pool,
00310                                      const svn_delta_editor_t *editor,
00311                                      void *edit_baton,
00312                                      svn_boolean_t *aborted);
00313 
00314 /** This function is only intended for use by svnserve.
00315  *
00316  * Perform CRAM-MD5 password authentication.  On success, return
00317  * SVN_NO_ERROR with *user set to the username and *success set to
00318  * TRUE.  On an error which can be reported to the client, report the
00319  * error and return SVN_NO_ERROR with *success set to FALSE.  On
00320  * communications failure, return an error.
00321  */
00322 svn_error_t *svn_ra_svn_cram_server(svn_ra_svn_conn_t *conn, apr_pool_t *pool,
00323                                     svn_config_t *pwdb, const char **user,
00324                                     svn_boolean_t *success);
00325 
00326 #ifdef __cplusplus
00327 }
00328 #endif /* __cplusplus */
00329 
00330 #endif  /* SVN_RA_SVN_H */

Generated on Wed Oct 20 01:47:45 2004 for Subversion by doxygen1.2.18