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 */