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