src/TortoiseMerge/svninclude/svn_ra_svn.h

   1 /**\r
   2  * @copyright\r
   3  * ====================================================================\r
   4  * Copyright (c) 2000-2006, 2008 CollabNet.  All rights reserved.\r
   5  *\r
   6  * This software is licensed as described in the file COPYING, which\r
   7  * you should have received as part of this distribution.  The terms\r
   8  * are also available at http://subversion.tigris.org/license-1.html.\r
   9  * If newer versions of this license are posted there, you may use a\r
  10  * newer version instead, at your option.\r
  11  *\r
  12  * This software consists of voluntary contributions made by many\r
  13  * individuals.  For exact contribution history, see the revision\r
  14  * history and logs, available at http://subversion.tigris.org/.\r
  15  * ====================================================================\r
  16  * @endcopyright\r
  17  *\r
  18  * @file svn_ra_svn.h\r
  19  * @brief libsvn_ra_svn functions used by the server\r
  20  */\r
  21 \r
  22 #ifndef SVN_RA_SVN_H\r
  23 #define SVN_RA_SVN_H\r
  24 \r
  25 #include <apr.h>\r
  26 #include <apr_pools.h>\r
  27 #include <apr_hash.h>\r
  28 #include <apr_tables.h>\r
  29 #include <apr_file_io.h>     /* for apr_file_t */\r
  30 #include <apr_network_io.h>  /* for apr_socket_t */\r
  31 \r
  32 #include "svn_types.h"\r
  33 #include "svn_string.h"\r
  34 #include "svn_config.h"\r
  35 #include "svn_delta.h"\r
  36 \r
  37 #ifdef __cplusplus\r
  38 extern "C" {\r
  39 #endif /* __cplusplus */\r
  40 \r
  41 /** The well-known svn port number. */\r
  42 #define SVN_RA_SVN_PORT 3690\r
  43 \r
  44 /** Currently-defined capabilities. */\r
  45 #define SVN_RA_SVN_CAP_EDIT_PIPELINE "edit-pipeline"\r
  46 #define SVN_RA_SVN_CAP_SVNDIFF1 "svndiff1"\r
  47 #define SVN_RA_SVN_CAP_ABSENT_ENTRIES "absent-entries"\r
  48 /* maps to SVN_RA_CAPABILITY_COMMIT_REVPROPS: */\r
  49 #define SVN_RA_SVN_CAP_COMMIT_REVPROPS "commit-revprops"\r
  50 /* maps to SVN_RA_CAPABILITY_MERGEINFO: */\r
  51 #define SVN_RA_SVN_CAP_MERGEINFO "mergeinfo"\r
  52 /* maps to SVN_RA_CAPABILITY_DEPTH: */\r
  53 #define SVN_RA_SVN_CAP_DEPTH "depth"\r
  54 /* maps to SVN_RA_CAPABILITY_LOG_REVPROPS */\r
  55 #define SVN_RA_SVN_CAP_LOG_REVPROPS "log-revprops"\r
  56 /* maps to SVN_RA_CAPABILITY_PARTIAL_REPLAY */\r
  57 #define SVN_RA_SVN_CAP_PARTIAL_REPLAY "partial-replay"\r
  58 \r
  59 /** ra_svn passes @c svn_dirent_t fields over the wire as a list of\r
  60  * words, these are the values used to represent each field.\r
  61  *\r
  62  * @defgroup ra_svn_dirent_fields Definitions of ra_svn dirent fields\r
  63  * @{\r
  64  */\r
  65 \r
  66 /** The ra_svn way of saying @c SVN_DIRENT_KIND. */\r
  67 #define SVN_RA_SVN_DIRENT_KIND "kind"\r
  68 \r
  69 /** The ra_svn way of saying @c SVN_DIRENT_SIZE. */\r
  70 #define SVN_RA_SVN_DIRENT_SIZE "size"\r
  71 \r
  72 /** The ra_svn way of saying @c SVN_DIRENT_HAS_PROPS. */\r
  73 #define SVN_RA_SVN_DIRENT_HAS_PROPS "has-props"\r
  74 \r
  75 /** The ra_svn way of saying @c SVN_DIRENT_CREATED_REV. */\r
  76 #define SVN_RA_SVN_DIRENT_CREATED_REV "created-rev"\r
  77 \r
  78 /** The ra_svn way of saying @c SVN_DIRENT_TIME. */\r
  79 #define SVN_RA_SVN_DIRENT_TIME "time"\r
  80 \r
  81 /** The ra_svn way of saying @c SVN_DIRENT_LAST_AUTHOR. */\r
  82 #define SVN_RA_SVN_DIRENT_LAST_AUTHOR "last-author"\r
  83 \r
  84 /** @} */\r
  85 \r
  86 /** A value used to indicate an optional number element in a tuple that was\r
  87  * not received.\r
  88  */\r
  89 #define SVN_RA_SVN_UNSPECIFIED_NUMBER ~((apr_uint64_t) 0)\r
  90 \r
  91 /** A specialized form of @c SVN_ERR to deal with errors which occur in an\r
  92  * svn_ra_svn_command_handler().\r
  93  *\r
  94  * An error returned with this macro will be passed back to the other side\r
  95  * of the connection.  Use this macro when performing the requested operation;\r
  96  * use the regular @c SVN_ERR when performing I/O with the client.\r
  97  */\r
  98 #define SVN_CMD_ERR(expr)                                     \\r
  99   do {                                                        \\r
 100     svn_error_t *svn_err__temp = (expr);                      \\r
 101     if (svn_err__temp)                                        \\r
 102       return svn_error_create(SVN_ERR_RA_SVN_CMD_ERR,         \\r
 103                               svn_err__temp, NULL);           \\r
 104   } while (0)\r
 105 \r
 106 /** an ra_svn connection. */\r
 107 typedef struct svn_ra_svn_conn_st svn_ra_svn_conn_t;\r
 108 \r
 109 /** Command handler, used by svn_ra_svn_handle_commands(). */\r
 110 typedef svn_error_t *(*svn_ra_svn_command_handler)(svn_ra_svn_conn_t *conn,\r
 111                                                    apr_pool_t *pool,\r
 112                                                    apr_array_header_t *params,\r
 113                                                    void *baton);\r
 114 \r
 115 /** Command table, used by svn_ra_svn_handle_commands().\r
 116  */\r
 117 typedef struct svn_ra_svn_cmd_entry_t\r
 118 {\r
 119   /** Name of the command */\r
 120   const char *cmdname;\r
 121 \r
 122   /** Handler for the command */\r
 123   svn_ra_svn_command_handler handler;\r
 124 \r
 125   /** Termination flag.  If set, command-handling will cease after\r
 126    * command is processed. */\r
 127   svn_boolean_t terminate;\r
 128 } svn_ra_svn_cmd_entry_t;\r
 129 \r
 130 /** Memory representation of an on-the-wire data item. */\r
 131 typedef struct svn_ra_svn_item_t\r
 132 {\r
 133   /** Variant indicator. */\r
 134   enum {\r
 135     SVN_RA_SVN_NUMBER,\r
 136     SVN_RA_SVN_STRING,\r
 137     SVN_RA_SVN_WORD,\r
 138     SVN_RA_SVN_LIST\r
 139   } kind;\r
 140   /** Variant data. */\r
 141   union {\r
 142     apr_uint64_t number;\r
 143     svn_string_t *string;\r
 144     const char *word;\r
 145 \r
 146     /** Contains @c svn_ra_svn_item_t's. */\r
 147     apr_array_header_t *list;\r
 148   } u;\r
 149 } svn_ra_svn_item_t;\r
 150 \r
 151 typedef svn_error_t *(*svn_ra_svn_edit_callback)(void *baton);\r
 152 \r
 153 /** Initialize a connection structure for the given socket or\r
 154  * input/output files.\r
 155  *\r
 156  * Either @a sock or @a in_file/@a out_file must be set, not both.\r
 157  */\r
 158 svn_ra_svn_conn_t *\r
 159 svn_ra_svn_create_conn(apr_socket_t *sock,\r
 160                        apr_file_t *in_file,\r
 161                        apr_file_t *out_file,\r
 162                        apr_pool_t *pool);\r
 163 \r
 164 /** Add the capabilities in @a list to @a conn's capabilities.\r
 165  * @a list contains svn_ra_svn_item_t entries (which should be of type\r
 166  * SVN_RA_SVN_WORD; a malformed data error will result if any are not).\r
 167  *\r
 168  * This is idempotent: if a given capability was already set for\r
 169  * @a conn, it remains set.\r
 170  */\r
 171 svn_error_t *\r
 172 svn_ra_svn_set_capabilities(svn_ra_svn_conn_t *conn,\r
 173                             apr_array_header_t *list);\r
 174 \r
 175 /** Return @c TRUE if @a conn has the capability @a capability, or\r
 176  * @c FALSE if it does not. */\r
 177 svn_boolean_t\r
 178 svn_ra_svn_has_capability(svn_ra_svn_conn_t *conn,\r
 179                           const char *capability);\r
 180 \r
 181 /** Returns the remote address of the connection as a string, if known,\r
 182  *  or NULL if inapplicable. */\r
 183 const char *\r
 184 svn_ra_svn_conn_remote_host(svn_ra_svn_conn_t *conn);\r
 185 \r
 186 /** Write a number over the net.\r
 187  *\r
 188  * Writes will be buffered until the next read or flush.\r
 189  */\r
 190 svn_error_t *\r
 191 svn_ra_svn_write_number(svn_ra_svn_conn_t *conn,\r
 192                         apr_pool_t *pool,\r
 193                         apr_uint64_t number);\r
 194 \r
 195 /** Write a string over the net.\r
 196  *\r
 197  * Writes will be buffered until the next read or flush.\r
 198  */\r
 199 svn_error_t *\r
 200 svn_ra_svn_write_string(svn_ra_svn_conn_t *conn,\r
 201                         apr_pool_t *pool,\r
 202                         const svn_string_t *str);\r
 203 \r
 204 /** Write a cstring over the net.\r
 205  *\r
 206  * Writes will be buffered until the next read or flush.\r
 207  */\r
 208 svn_error_t *\r
 209 svn_ra_svn_write_cstring(svn_ra_svn_conn_t *conn,\r
 210                          apr_pool_t *pool,\r
 211                          const char *s);\r
 212 \r
 213 /** Write a word over the net.\r
 214  *\r
 215  * Writes will be buffered until the next read or flush.\r
 216  */\r
 217 svn_error_t *\r
 218 svn_ra_svn_write_word(svn_ra_svn_conn_t *conn,\r
 219                       apr_pool_t *pool,\r
 220                       const char *word);\r
 221 \r
 222 /** Write a list of properties over the net.  @a props is allowed to be NULL,\r
 223  * in which case an empty list will be written out.\r
 224  *\r
 225  * @since New in 1.5.\r
 226  */\r
 227 svn_error_t *\r
 228 svn_ra_svn_write_proplist(svn_ra_svn_conn_t *conn,\r
 229                           apr_pool_t *pool,\r
 230                           apr_hash_t *props);\r
 231 \r
 232 /** Begin a list.  Writes will be buffered until the next read or flush. */\r
 233 svn_error_t *\r
 234 svn_ra_svn_start_list(svn_ra_svn_conn_t *conn,\r
 235                       apr_pool_t *pool);\r
 236 \r
 237 /** End a list.  Writes will be buffered until the next read or flush. */\r
 238 svn_error_t *\r
 239 svn_ra_svn_end_list(svn_ra_svn_conn_t *conn,\r
 240                     apr_pool_t *pool);\r
 241 \r
 242 /** Flush the write buffer.\r
 243  *\r
 244  * Normally this shouldn't be necessary, since the write buffer is flushed\r
 245  * when a read is attempted.\r
 246  */\r
 247 svn_error_t *\r
 248 svn_ra_svn_flush(svn_ra_svn_conn_t *conn,\r
 249                  apr_pool_t *pool);\r
 250 \r
 251 /** Write a tuple, using a printf-like interface.\r
 252  *\r
 253  * The format string @a fmt may contain:\r
 254  *\r
 255  *@verbatim\r
 256      Spec  Argument type         Item type\r
 257      ----  --------------------  ---------\r
 258      n     apr_uint64_t          Number\r
 259      r     svn_revnum_t          Number\r
 260      s     const svn_string_t *  String\r
 261      c     const char *          String\r
 262      w     const char *          Word\r
 263      b     svn_boolean_t         Word ("true" or "false")\r
 264      (                           Begin tuple\r
 265      )                           End tuple\r
 266      ?                           Remaining elements optional\r
 267      ! (at beginning or end)     Suppress opening or closing of tuple\r
 268   @endverbatim\r
 269  *\r
 270  * Inside the optional part of a tuple, 'r' values may be @c\r
 271  * SVN_INVALID_REVNUM, 'n' values may be\r
 272  * SVN_RA_SVN_UNSPECIFIED_NUMBER, and 's', 'c', and 'w' values may be\r
 273  * @c NULL; in these cases no data will be written.  'b' and '(' may\r
 274  * not appear in the optional part of a tuple.  Either all or none of\r
 275  * the optional values should be valid.\r
 276  *\r
 277  * (If we ever have a need for an optional boolean value, we should\r
 278  * invent a 'B' specifier which stores a boolean into an int, using -1\r
 279  * for unspecified.  Right now there is no need for such a thing.)\r
 280  *\r
 281  * Use the '!' format specifier to write partial tuples when you have\r
 282  * to transmit an array or other unusual data.  For example, to write\r
 283  * a tuple containing a revision, an array of words, and a boolean:\r
 284  * @verbatim\r
 285      SVN_ERR(svn_ra_svn_write_tuple(conn, pool, "r(!", rev));\r
 286      for (i = 0; i < n; i++)\r
 287        SVN_ERR(svn_ra_svn_write_word(conn, pool, words[i]));\r
 288      SVN_ERR(svn_ra_svn_write_tuple(conn, pool, "!)b", flag)); @endverbatim\r
 289  */\r
 290 svn_error_t *\r
 291 svn_ra_svn_write_tuple(svn_ra_svn_conn_t *conn,\r
 292                        apr_pool_t *pool,\r
 293                        const char *fmt, ...);\r
 294 \r
 295 /** Read an item from the network into @a *item. */\r
 296 svn_error_t *\r
 297 svn_ra_svn_read_item(svn_ra_svn_conn_t *conn,\r
 298                      apr_pool_t *pool,\r
 299                      svn_ra_svn_item_t **item);\r
 300 \r
 301 /** Scan data on @a conn until we find something which looks like the\r
 302  * beginning of an svn server greeting (an open paren followed by a\r
 303  * whitespace character).  This function is appropriate for beginning\r
 304  * a client connection opened in tunnel mode, since people's dotfiles\r
 305  * sometimes write output to stdout.  It may only be called at the\r
 306  * beginning of a client connection.\r
 307  */\r
 308 svn_error_t *\r
 309 svn_ra_svn_skip_leading_garbage(svn_ra_svn_conn_t *conn,\r
 310                                 apr_pool_t *pool);\r
 311 \r
 312 /** Parse an array of @c svn_sort__item_t structures as a tuple, using a\r
 313  * printf-like interface.  The format string @a fmt may contain:\r
 314  *\r
 315  *@verbatim\r
 316      Spec  Argument type          Item type\r
 317      ----  --------------------   ---------\r
 318      n     apr_uint64_t *         Number\r
 319      r     svn_revnum_t *         Number\r
 320      s     svn_string_t **        String\r
 321      c     const char **          String\r
 322      w     const char **          Word\r
 323      b     svn_boolean_t *        Word ("true" or "false")\r
 324      B     apr_uint64_t *         Word ("true" or "false")\r
 325      l     apr_array_header_t **  List\r
 326      (                            Begin tuple\r
 327      )                            End tuple\r
 328      ?                            Tuple is allowed to end here\r
 329   @endverbatim\r
 330  *\r
 331  * Note that a tuple is only allowed to end precisely at a '?', or at\r
 332  * the end of the specification.  So if @a fmt is "c?cc" and @a list\r
 333  * contains two elements, an error will result.\r
 334  *\r
 335  * 'B' is similar to 'b', but may be used in the optional tuple specification.\r
 336  * It returns TRUE, FALSE, or SVN_RA_SVN_UNSPECIFIED_NUMBER.\r
 337  *\r
 338  * If an optional part of a tuple contains no data, 'r' values will be\r
 339  * set to @c SVN_INVALID_REVNUM, 'n' and 'B' values will be set to\r
 340  * SVN_RA_SVN_UNSPECIFIED_NUMBER, and 's', 'c', 'w', and 'l' values\r
 341  * will be set to @c NULL.  'b' may not appear inside an optional\r
 342  * tuple specification; use 'B' instead.\r
 343  */\r
 344 svn_error_t *\r
 345 svn_ra_svn_parse_tuple(apr_array_header_t *list,\r
 346                        apr_pool_t *pool,\r
 347                        const char *fmt, ...);\r
 348 \r
 349 /** Read a tuple from the network and parse it as a tuple, using the\r
 350  * format string notation from svn_ra_svn_parse_tuple().\r
 351  */\r
 352 svn_error_t *\r
 353 svn_ra_svn_read_tuple(svn_ra_svn_conn_t *conn,\r
 354                       apr_pool_t *pool,\r
 355                       const char *fmt, ...);\r
 356 \r
 357 /** Parse an array of @c svn_ra_svn_item_t structures as a list of\r
 358  * properties, storing the properties in a hash table.\r
 359  *\r
 360  * @since New in 1.5.\r
 361  */\r
 362 svn_error_t *\r
 363 svn_ra_svn_parse_proplist(apr_array_header_t *list,\r
 364                           apr_pool_t *pool,\r
 365                           apr_hash_t **props);\r
 366 \r
 367 /** Read a command response from the network and parse it as a tuple, using\r
 368  * the format string notation from svn_ra_svn_parse_tuple().\r
 369  */\r
 370 svn_error_t *\r
 371 svn_ra_svn_read_cmd_response(svn_ra_svn_conn_t *conn,\r
 372                              apr_pool_t *pool,\r
 373                              const char *fmt, ...);\r
 374 \r
 375 /** Accept commands over the network and handle them according to @a\r
 376  * commands.  Command handlers will be passed @a conn, a subpool of @a\r
 377  * pool (cleared after each command is handled), the parameters of the\r
 378  * command, and @a baton.  Commands will be accepted until a\r
 379  * terminating command is received (a command with "terminate" set in\r
 380  * the command table).  If a command handler returns an error wrapped\r
 381  * in SVN_RA_SVN_CMD_ERR (see the @c SVN_CMD_ERR macro), the error\r
 382  * will be reported to the other side of the connection and the\r
 383  * command loop will continue; any other kind of error (typically a\r
 384  * network or protocol error) is passed through to the caller.\r
 385  *\r
 386  * @since New in 1.6.\r
 387  *\r
 388  */\r
 389 svn_error_t *\r
 390 svn_ra_svn_handle_commands2(svn_ra_svn_conn_t *conn,\r
 391                             apr_pool_t *pool,\r
 392                             const svn_ra_svn_cmd_entry_t *commands,\r
 393                             void *baton,\r
 394                             svn_boolean_t error_on_disconnect);\r
 395 \r
 396 /** Similar to svn_ra_svn_handle_commands2 but @a error_on_disconnect\r
 397  * is always @c FALSE.\r
 398  *\r
 399  * @deprecated Provided for backward compatibility with the 1.5 API.\r
 400  */\r
 401 SVN_DEPRECATED\r
 402 svn_error_t *\r
 403 svn_ra_svn_handle_commands(svn_ra_svn_conn_t *conn,\r
 404                            apr_pool_t *pool,\r
 405                            const svn_ra_svn_cmd_entry_t *commands,\r
 406                            void *baton);\r
 407 \r
 408 /** Write a command over the network, using the same format string notation\r
 409  * as svn_ra_svn_write_tuple().\r
 410  */\r
 411 svn_error_t *\r
 412 svn_ra_svn_write_cmd(svn_ra_svn_conn_t *conn,\r
 413                      apr_pool_t *pool,\r
 414                      const char *cmdname,\r
 415                      const char *fmt, ...);\r
 416 \r
 417 /** Write a successful command response over the network, using the\r
 418  * same format string notation as svn_ra_svn_write_tuple().  Do not use\r
 419  * partial tuples with this function; if you need to use partial\r
 420  * tuples, just write out the "success" and argument tuple by hand.\r
 421  */\r
 422 svn_error_t *\r
 423 svn_ra_svn_write_cmd_response(svn_ra_svn_conn_t *conn,\r
 424                               apr_pool_t *pool,\r
 425                               const char *fmt, ...);\r
 426 \r
 427 /** Write an unsuccessful command response over the network. */\r
 428 svn_error_t *\r
 429 svn_ra_svn_write_cmd_failure(svn_ra_svn_conn_t *conn,\r
 430                              apr_pool_t *pool,\r
 431                              svn_error_t *err);\r
 432 \r
 433 /** Set @a *editor and @a *edit_baton to an editor which will pass editing\r
 434  * operations over the network, using @a conn and @a pool.\r
 435  *\r
 436  * Upon successful completion of the edit, the editor will invoke @a callback\r
 437  * with @a callback_baton as an argument.\r
 438  */\r
 439 void\r
 440 svn_ra_svn_get_editor(const svn_delta_editor_t **editor,\r
 441                       void **edit_baton,\r
 442                       svn_ra_svn_conn_t *conn,\r
 443                       apr_pool_t *pool,\r
 444                       svn_ra_svn_edit_callback callback,\r
 445                       void *callback_baton);\r
 446 \r
 447 /** Receive edit commands over the network and use them to drive @a editor\r
 448  * with @a edit_baton.  On return, @a *aborted will be set if the edit was\r
 449  * aborted.  The drive can be terminated with a finish-replay command only\r
 450  * if @a for_replay is TRUE.\r
 451  */\r
 452 svn_error_t *\r
 453 svn_ra_svn_drive_editor2(svn_ra_svn_conn_t *conn,\r
 454                          apr_pool_t *pool,\r
 455                          const svn_delta_editor_t *editor,\r
 456                          void *edit_baton,\r
 457                          svn_boolean_t *aborted,\r
 458                          svn_boolean_t for_replay);\r
 459 \r
 460 /** Like svn_ra_svn_drive_editor2, but with @a for_replay always FALSE.\r
 461  */\r
 462 svn_error_t *\r
 463 svn_ra_svn_drive_editor(svn_ra_svn_conn_t *conn,\r
 464                         apr_pool_t *pool,\r
 465                         const svn_delta_editor_t *editor,\r
 466                         void *edit_baton,\r
 467                         svn_boolean_t *aborted);\r
 468 \r
 469 /** This function is only intended for use by svnserve.\r
 470  *\r
 471  * Perform CRAM-MD5 password authentication.  On success, return\r
 472  * SVN_NO_ERROR with *user set to the username and *success set to\r
 473  * TRUE.  On an error which can be reported to the client, report the\r
 474  * error and return SVN_NO_ERROR with *success set to FALSE.  On\r
 475  * communications failure, return an error.\r
 476  */\r
 477 svn_error_t *\r
 478 svn_ra_svn_cram_server(svn_ra_svn_conn_t *conn,\r
 479                        apr_pool_t *pool,\r
 480                        svn_config_t *pwdb,\r
 481                        const char **user,\r
 482                        svn_boolean_t *success);\r
 483 \r
 484 /**\r
 485  * Get libsvn_ra_svn version information.\r
 486  * @since New in 1.1.\r
 487  */\r
 488 const svn_version_t *\r
 489 svn_ra_svn_version(void);\r
 490 \r
 491 #ifdef __cplusplus\r
 492 }\r
 493 #endif /* __cplusplus */\r
 494 \r
 495 #endif  /* SVN_RA_SVN_H */\r