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