/** * @copyright * ==================================================================== * Copyright (c) 2000-2006, 2008 CollabNet. All rights reserved. * * This software is licensed as described in the file COPYING, which * you should have received as part of this distribution. The terms * are also available at http://subversion.tigris.org/license-1.html. * If newer versions of this license are posted there, you may use a * newer version instead, at your option. * * This software consists of voluntary contributions made by many * individuals. For exact contribution history, see the revision * history and logs, available at http://subversion.tigris.org/. * ==================================================================== * @endcopyright * * @file svn_ra_svn.h * @brief libsvn_ra_svn functions used by the server */ #ifndef SVN_RA_SVN_H #define SVN_RA_SVN_H #include <apr.h> #include <apr_pools.h> #include <apr_hash.h> #include <apr_tables.h> #include <apr_file_io.h> /* for apr_file_t */ #include <apr_network_io.h> /* for apr_socket_t */ #include "svn_types.h" #include "svn_string.h" #include "svn_config.h" #include "svn_delta.h" #ifdef __cplusplus extern "C" { #endif /* __cplusplus */ /** The well-known svn port number. */ #define SVN_RA_SVN_PORT 3690 /** Currently-defined capabilities. */ #define SVN_RA_SVN_CAP_EDIT_PIPELINE "edit-pipeline" #define SVN_RA_SVN_CAP_SVNDIFF1 "svndiff1" #define SVN_RA_SVN_CAP_ABSENT_ENTRIES "absent-entries" /* maps to SVN_RA_CAPABILITY_COMMIT_REVPROPS: */ #define SVN_RA_SVN_CAP_COMMIT_REVPROPS "commit-revprops" /* maps to SVN_RA_CAPABILITY_MERGEINFO: */ #define SVN_RA_SVN_CAP_MERGEINFO "mergeinfo" /* maps to SVN_RA_CAPABILITY_DEPTH: */ #define SVN_RA_SVN_CAP_DEPTH "depth" /* maps to SVN_RA_CAPABILITY_LOG_REVPROPS */ #define SVN_RA_SVN_CAP_LOG_REVPROPS "log-revprops" /* maps to SVN_RA_CAPABILITY_PARTIAL_REPLAY */ #define SVN_RA_SVN_CAP_PARTIAL_REPLAY "partial-replay" /** ra_svn passes @c svn_dirent_t fields over the wire as a list of * words, these are the values used to represent each field. * * @defgroup ra_svn_dirent_fields Definitions of ra_svn dirent fields * @{ */ /** The ra_svn way of saying @c SVN_DIRENT_KIND. */ #define SVN_RA_SVN_DIRENT_KIND "kind" /** The ra_svn way of saying @c SVN_DIRENT_SIZE. */ #define SVN_RA_SVN_DIRENT_SIZE "size" /** The ra_svn way of saying @c SVN_DIRENT_HAS_PROPS. */ #define SVN_RA_SVN_DIRENT_HAS_PROPS "has-props" /** The ra_svn way of saying @c SVN_DIRENT_CREATED_REV. */ #define SVN_RA_SVN_DIRENT_CREATED_REV "created-rev" /** The ra_svn way of saying @c SVN_DIRENT_TIME. */ #define SVN_RA_SVN_DIRENT_TIME "time" /** The ra_svn way of saying @c SVN_DIRENT_LAST_AUTHOR. */ #define SVN_RA_SVN_DIRENT_LAST_AUTHOR "last-author" /** @} */ /** A value used to indicate an optional number element in a tuple that was * not received. */ #define SVN_RA_SVN_UNSPECIFIED_NUMBER ~((apr_uint64_t) 0) /** A specialized form of @c SVN_ERR to deal with errors which occur in an * svn_ra_svn_command_handler(). * * An error returned with this macro will be passed back to the other side * of the connection. Use this macro when performing the requested operation; * use the regular @c SVN_ERR when performing I/O with the client. */ #define SVN_CMD_ERR(expr) \ do { \ svn_error_t *svn_err__temp = (expr); \ if (svn_err__temp) \ return svn_error_create(SVN_ERR_RA_SVN_CMD_ERR, \ svn_err__temp, NULL); \ } while (0) /** an ra_svn connection. */ typedef struct svn_ra_svn_conn_st svn_ra_svn_conn_t; /** Command handler, used by svn_ra_svn_handle_commands(). */ typedef svn_error_t *(*svn_ra_svn_command_handler)(svn_ra_svn_conn_t *conn, apr_pool_t *pool, apr_array_header_t *params, void *baton); /** Command table, used by svn_ra_svn_handle_commands(). */ typedef struct svn_ra_svn_cmd_entry_t { /** Name of the command */ const char *cmdname; /** Handler for the command */ svn_ra_svn_command_handler handler; /** Termination flag. If set, command-handling will cease after * command is processed. */ svn_boolean_t terminate; } svn_ra_svn_cmd_entry_t; /** Memory representation of an on-the-wire data item. */ typedef struct svn_ra_svn_item_t { /** Variant indicator. */ enum { SVN_RA_SVN_NUMBER, SVN_RA_SVN_STRING, SVN_RA_SVN_WORD, SVN_RA_SVN_LIST } kind; /** Variant data. */ union { apr_uint64_t number; svn_string_t *string; const char *word; /** Contains @c svn_ra_svn_item_t's. */ apr_array_header_t *list; } u; } svn_ra_svn_item_t; typedef svn_error_t *(*svn_ra_svn_edit_callback)(void *baton); /** Initialize a connection structure for the given socket or * input/output files. * * Either @a sock or @a in_file/@a out_file must be set, not both. */ svn_ra_svn_conn_t * svn_ra_svn_create_conn(apr_socket_t *sock, apr_file_t *in_file, apr_file_t *out_file, apr_pool_t *pool); /** Add the capabilities in @a list to @a conn's capabilities. * @a list contains svn_ra_svn_item_t entries (which should be of type * SVN_RA_SVN_WORD; a malformed data error will result if any are not). * * This is idempotent: if a given capability was already set for * @a conn, it remains set. */ svn_error_t * svn_ra_svn_set_capabilities(svn_ra_svn_conn_t *conn, apr_array_header_t *list); /** Return @c TRUE if @a conn has the capability @a capability, or * @c FALSE if it does not. */ svn_boolean_t svn_ra_svn_has_capability(svn_ra_svn_conn_t *conn, const char *capability); /** Returns the remote address of the connection as a string, if known, * or NULL if inapplicable. */ const char * svn_ra_svn_conn_remote_host(svn_ra_svn_conn_t *conn); /** Write a number over the net. * * Writes will be buffered until the next read or flush. */ svn_error_t * svn_ra_svn_write_number(svn_ra_svn_conn_t *conn, apr_pool_t *pool, apr_uint64_t number); /** Write a string over the net. * * Writes will be buffered until the next read or flush. */ svn_error_t * svn_ra_svn_write_string(svn_ra_svn_conn_t *conn, apr_pool_t *pool, const svn_string_t *str); /** Write a cstring over the net. * * Writes will be buffered until the next read or flush. */ svn_error_t * svn_ra_svn_write_cstring(svn_ra_svn_conn_t *conn, apr_pool_t *pool, const char *s); /** Write a word over the net. * * Writes will be buffered until the next read or flush. */ svn_error_t * svn_ra_svn_write_word(svn_ra_svn_conn_t *conn, apr_pool_t *pool, const char *word); /** Write a list of properties over the net. @a props is allowed to be NULL, * in which case an empty list will be written out. * * @since New in 1.5. */ svn_error_t * svn_ra_svn_write_proplist(svn_ra_svn_conn_t *conn, apr_pool_t *pool, apr_hash_t *props); /** Begin a list. Writes will be buffered until the next read or flush. */ svn_error_t * svn_ra_svn_start_list(svn_ra_svn_conn_t *conn, apr_pool_t *pool); /** End a list. Writes will be buffered until the next read or flush. */ svn_error_t * svn_ra_svn_end_list(svn_ra_svn_conn_t *conn, apr_pool_t *pool); /** Flush the write buffer. * * Normally this shouldn't be necessary, since the write buffer is flushed * when a read is attempted. */ svn_error_t * svn_ra_svn_flush(svn_ra_svn_conn_t *conn, apr_pool_t *pool); /** Write a tuple, using a printf-like interface. * * The format string @a fmt may contain: * *@verbatim Spec Argument type Item type ---- -------------------- --------- n apr_uint64_t Number r svn_revnum_t Number s const svn_string_t * String c const char * String w const char * Word b svn_boolean_t Word ("true" or "false") ( Begin tuple ) End tuple ? Remaining elements optional ! (at beginning or end) Suppress opening or closing of tuple @endverbatim * * Inside the optional part of a tuple, 'r' values may be @c * SVN_INVALID_REVNUM, 'n' values may be * SVN_RA_SVN_UNSPECIFIED_NUMBER, and 's', 'c', and 'w' values may be * @c NULL; in these cases no data will be written. 'b' and '(' may * not appear in the optional part of a tuple. Either all or none of * the optional values should be valid. * * (If we ever have a need for an optional boolean value, we should * invent a 'B' specifier which stores a boolean into an int, using -1 * for unspecified. Right now there is no need for such a thing.) * * Use the '!' format specifier to write partial tuples when you have * to transmit an array or other unusual data. For example, to write * a tuple containing a revision, an array of words, and a boolean: * @verbatim SVN_ERR(svn_ra_svn_write_tuple(conn, pool, "r(!", rev)); for (i = 0; i < n; i++) SVN_ERR(svn_ra_svn_write_word(conn, pool, words[i])); SVN_ERR(svn_ra_svn_write_tuple(conn, pool, "!)b", flag)); @endverbatim */ svn_error_t * svn_ra_svn_write_tuple(svn_ra_svn_conn_t *conn, apr_pool_t *pool, const char *fmt, ...); /** Read an item from the network into @a *item. */ svn_error_t * svn_ra_svn_read_item(svn_ra_svn_conn_t *conn, apr_pool_t *pool, svn_ra_svn_item_t **item); /** Scan data on @a conn until we find something which looks like the * beginning of an svn server greeting (an open paren followed by a * whitespace character). This function is appropriate for beginning * a client connection opened in tunnel mode, since people's dotfiles * sometimes write output to stdout. It may only be called at the * beginning of a client connection. */ svn_error_t * svn_ra_svn_skip_leading_garbage(svn_ra_svn_conn_t *conn, apr_pool_t *pool); /** Parse an array of @c svn_sort__item_t structures as a tuple, using a * printf-like interface. The format string @a fmt may contain: * *@verbatim Spec Argument type Item type ---- -------------------- --------- n apr_uint64_t * Number r svn_revnum_t * Number s svn_string_t ** String c const char ** String w const char ** Word b svn_boolean_t * Word ("true" or "false") B apr_uint64_t * Word ("true" or "false") l apr_array_header_t ** List ( Begin tuple ) End tuple ? Tuple is allowed to end here @endverbatim * * Note that a tuple is only allowed to end precisely at a '?', or at * the end of the specification. So if @a fmt is "c?cc" and @a list * contains two elements, an error will result. * * 'B' is similar to 'b', but may be used in the optional tuple specification. * It returns TRUE, FALSE, or SVN_RA_SVN_UNSPECIFIED_NUMBER. * * If an optional part of a tuple contains no data, 'r' values will be * set to @c SVN_INVALID_REVNUM, 'n' and 'B' values will be set to * SVN_RA_SVN_UNSPECIFIED_NUMBER, and 's', 'c', 'w', and 'l' values * will be set to @c NULL. 'b' may not appear inside an optional * tuple specification; use 'B' instead. */ svn_error_t * svn_ra_svn_parse_tuple(apr_array_header_t *list, apr_pool_t *pool, const char *fmt, ...); /** Read a tuple from the network and parse it as a tuple, using the * format string notation from svn_ra_svn_parse_tuple(). */ svn_error_t * svn_ra_svn_read_tuple(svn_ra_svn_conn_t *conn, apr_pool_t *pool, const char *fmt, ...); /** Parse an array of @c svn_ra_svn_item_t structures as a list of * properties, storing the properties in a hash table. * * @since New in 1.5. */ svn_error_t * svn_ra_svn_parse_proplist(apr_array_header_t *list, apr_pool_t *pool, apr_hash_t **props); /** Read a command response from the network and parse it as a tuple, using * the format string notation from svn_ra_svn_parse_tuple(). */ svn_error_t * svn_ra_svn_read_cmd_response(svn_ra_svn_conn_t *conn, apr_pool_t *pool, const char *fmt, ...); /** Accept commands over the network and handle them according to @a * commands. Command handlers will be passed @a conn, a subpool of @a * pool (cleared after each command is handled), the parameters of the * command, and @a baton. Commands will be accepted until a * terminating command is received (a command with "terminate" set in * the command table). If a command handler returns an error wrapped * in SVN_RA_SVN_CMD_ERR (see the @c SVN_CMD_ERR macro), the error * will be reported to the other side of the connection and the * command loop will continue; any other kind of error (typically a * network or protocol error) is passed through to the caller. * * @since New in 1.6. * */ svn_error_t * svn_ra_svn_handle_commands2(svn_ra_svn_conn_t *conn, apr_pool_t *pool, const svn_ra_svn_cmd_entry_t *commands, void *baton, svn_boolean_t error_on_disconnect); /** Similar to svn_ra_svn_handle_commands2 but @a error_on_disconnect * is always @c FALSE. * * @deprecated Provided for backward compatibility with the 1.5 API. */ SVN_DEPRECATED svn_error_t * svn_ra_svn_handle_commands(svn_ra_svn_conn_t *conn, apr_pool_t *pool, const svn_ra_svn_cmd_entry_t *commands, void *baton); /** Write a command over the network, using the same format string notation * as svn_ra_svn_write_tuple(). */ svn_error_t * svn_ra_svn_write_cmd(svn_ra_svn_conn_t *conn, apr_pool_t *pool, const char *cmdname, const char *fmt, ...); /** Write a successful command response over the network, using the * same format string notation as svn_ra_svn_write_tuple(). Do not use * partial tuples with this function; if you need to use partial * tuples, just write out the "success" and argument tuple by hand. */ svn_error_t * svn_ra_svn_write_cmd_response(svn_ra_svn_conn_t *conn, apr_pool_t *pool, const char *fmt, ...); /** Write an unsuccessful command response over the network. */ svn_error_t * svn_ra_svn_write_cmd_failure(svn_ra_svn_conn_t *conn, apr_pool_t *pool, svn_error_t *err); /** Set @a *editor and @a *edit_baton to an editor which will pass editing * operations over the network, using @a conn and @a pool. * * Upon successful completion of the edit, the editor will invoke @a callback * with @a callback_baton as an argument. */ void svn_ra_svn_get_editor(const svn_delta_editor_t **editor, void **edit_baton, svn_ra_svn_conn_t *conn, apr_pool_t *pool, svn_ra_svn_edit_callback callback, void *callback_baton); /** Receive edit commands over the network and use them to drive @a editor * with @a edit_baton. On return, @a *aborted will be set if the edit was * aborted. The drive can be terminated with a finish-replay command only * if @a for_replay is TRUE. */ svn_error_t * svn_ra_svn_drive_editor2(svn_ra_svn_conn_t *conn, apr_pool_t *pool, const svn_delta_editor_t *editor, void *edit_baton, svn_boolean_t *aborted, svn_boolean_t for_replay); /** Like svn_ra_svn_drive_editor2, but with @a for_replay always FALSE. */ svn_error_t * svn_ra_svn_drive_editor(svn_ra_svn_conn_t *conn, apr_pool_t *pool, const svn_delta_editor_t *editor, void *edit_baton, svn_boolean_t *aborted); /** This function is only intended for use by svnserve. * * Perform CRAM-MD5 password authentication. On success, return * SVN_NO_ERROR with *user set to the username and *success set to * TRUE. On an error which can be reported to the client, report the * error and return SVN_NO_ERROR with *success set to FALSE. On * communications failure, return an error. */ svn_error_t * svn_ra_svn_cram_server(svn_ra_svn_conn_t *conn, apr_pool_t *pool, svn_config_t *pwdb, const char **user, svn_boolean_t *success); /** * Get libsvn_ra_svn version information. * @since New in 1.1. */ const svn_version_t * svn_ra_svn_version(void); #ifdef __cplusplus } #endif /* __cplusplus */ #endif /* SVN_RA_SVN_H */