Subversion
svn_types.h
Go to the documentation of this file.
00001 /**
00002  * @copyright
00003  * ====================================================================
00004  *    Licensed to the Apache Software Foundation (ASF) under one
00005  *    or more contributor license agreements.  See the NOTICE file
00006  *    distributed with this work for additional information
00007  *    regarding copyright ownership.  The ASF licenses this file
00008  *    to you under the Apache License, Version 2.0 (the
00009  *    "License"); you may not use this file except in compliance
00010  *    with the License.  You may obtain a copy of the License at
00011  *
00012  *      http://www.apache.org/licenses/LICENSE-2.0
00013  *
00014  *    Unless required by applicable law or agreed to in writing,
00015  *    software distributed under the License is distributed on an
00016  *    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
00017  *    KIND, either express or implied.  See the License for the
00018  *    specific language governing permissions and limitations
00019  *    under the License.
00020  * ====================================================================
00021  * @endcopyright
00022  *
00023  * @file svn_types.h
00024  * @brief Subversion's data types
00025  */
00026 
00027 #ifndef SVN_TYPES_H
00028 #define SVN_TYPES_H
00029 
00030 /* ### this should go away, but it causes too much breakage right now */
00031 #include <stdlib.h>
00032 
00033 #include <apr.h>         /* for apr_size_t, apr_int64_t, ... */
00034 #include <apr_errno.h>   /* for apr_status_t */
00035 #include <apr_pools.h>   /* for apr_pool_t */
00036 #include <apr_hash.h>    /* for apr_hash_t */
00037 #include <apr_tables.h>  /* for apr_array_push() */
00038 #include <apr_time.h>    /* for apr_time_t */
00039 #include <apr_strings.h> /* for apr_atoi64() */
00040 
00041 #ifdef __cplusplus
00042 extern "C" {
00043 #endif /* __cplusplus */
00044 
00045 
00046 
00047 /** Macro used to mark deprecated functions.
00048  *
00049  * @since New in 1.6.
00050  */
00051 #ifndef SVN_DEPRECATED
00052 # if !defined(SWIGPERL) && !defined(SWIGPYTHON) && !defined(SWIGRUBY)
00053 #  if defined(__GNUC__) && (__GNUC__ >= 4 || (__GNUC__==3 && __GNUC_MINOR__>=1))
00054 #   define SVN_DEPRECATED __attribute__((deprecated))
00055 #  elif defined(_MSC_VER) && _MSC_VER >= 1300
00056 #   define SVN_DEPRECATED __declspec(deprecated)
00057 #  else
00058 #   define SVN_DEPRECATED
00059 #  endif
00060 # else
00061 #  define SVN_DEPRECATED
00062 # endif
00063 #endif
00064 
00065 
00066 /** Indicate whether the current platform supports unaligned data access.
00067  *
00068  * On the majority of machines running SVN (x86 / x64), unaligned access
00069  * is much cheaper than repeated aligned access. Define this macro to 1
00070  * on those machines.
00071  * Unaligned access on other machines (e.g. IA64) will trigger memory
00072  * access faults or simply misbehave.
00073  *
00074  * @since New in 1.7.
00075  */
00076 #ifndef SVN_UNALIGNED_ACCESS_IS_OK
00077 # if defined(_M_IX86) || defined(_M_X64) || defined(i386) || defined(__x86_64)
00078 #  define SVN_UNALIGNED_ACCESS_IS_OK 1
00079 # else
00080 #  define SVN_UNALIGNED_ACCESS_IS_OK 0
00081 # endif
00082 #endif
00083 
00084 
00085 /** Subversion error object.
00086  *
00087  * Defined here, rather than in svn_error.h, to avoid a recursive @#include
00088  * situation.
00089  */
00090 typedef struct svn_error_t
00091 {
00092   /** APR error value; possibly an SVN_ custom error code (see
00093    * `svn_error_codes.h' for a full listing).
00094    */
00095   apr_status_t apr_err;
00096 
00097   /** Details from the producer of error.
00098    *
00099    * Note that if this error was generated by Subversion's API, you'll
00100    * probably want to use svn_err_best_message() to get a single
00101    * descriptive string for this error chain (see the @a child member)
00102    * or svn_handle_error2() to print the error chain in full.  This is
00103    * because Subversion's API functions sometimes add many links to
00104    * the error chain that lack details (used only to produce virtual
00105    * stack traces).  (Use svn_error_purge_tracing() to remove those
00106    * trace-only links from the error chain.)
00107    */
00108   const char *message;
00109 
00110   /** Pointer to the error we "wrap" (may be @c NULL).  Via this
00111    * member, individual error object can be strung together into an
00112    * "error chain".
00113    */
00114   struct svn_error_t *child;
00115 
00116   /** The pool in which this error object is allocated.  (If
00117    * Subversion's APIs are used to manage error chains, then this pool
00118    * will contain the whole error chain of which this object is a
00119    * member.) */
00120   apr_pool_t *pool;
00121 
00122   /** Source file where the error originated (iff @c SVN_DEBUG;
00123    * undefined otherwise).
00124    */
00125   const char *file;
00126 
00127   /** Source line where the error originated (iff @c SVN_DEBUG;
00128    * undefined otherwise).
00129    */
00130   long line;
00131 
00132 } svn_error_t;
00133 
00134 /* See svn_version.h.
00135    Defined here to avoid including svn_version.h from all public headers. */
00136 typedef struct svn_version_t svn_version_t;
00137 
00138 /** @defgroup APR_ARRAY_compat_macros APR Array Compatibility Helper Macros
00139  * These macros are provided by APR itself from version 1.3.
00140  * Definitions are provided here for when using older versions of APR.
00141  * @{
00142  */
00143 
00144 /** index into an apr_array_header_t */
00145 #ifndef APR_ARRAY_IDX
00146 #define APR_ARRAY_IDX(ary,i,type) (((type *)(ary)->elts)[i])
00147 #endif
00148 
00149 /** easier array-pushing syntax */
00150 #ifndef APR_ARRAY_PUSH
00151 #define APR_ARRAY_PUSH(ary,type) (*((type *)apr_array_push(ary)))
00152 #endif
00153 
00154 /** @} */
00155 
00156 /** @defgroup apr_hash_utilities APR Hash Table Helpers
00157  * These functions enable the caller to dereference an APR hash table index
00158  * without type casts or temporary variables.
00159  *
00160  * ### These are private, and may go away when APR implements them natively.
00161  * @{
00162  */
00163 
00164 /** Return the key of the hash table entry indexed by @a hi. */
00165 const void *
00166 svn__apr_hash_index_key(const apr_hash_index_t *hi);
00167 
00168 /** Return the key length of the hash table entry indexed by @a hi. */
00169 apr_ssize_t
00170 svn__apr_hash_index_klen(const apr_hash_index_t *hi);
00171 
00172 /** Return the value of the hash table entry indexed by @a hi. */
00173 void *
00174 svn__apr_hash_index_val(const apr_hash_index_t *hi);
00175 
00176 /** On Windows, APR_STATUS_IS_ENOTDIR includes several kinds of
00177  * invalid-pathname error but not ERROR_INVALID_NAME, so we include it.
00178  * We also include ERROR_DIRECTORY as that was not included in apr versions
00179  * before 1.4.0 and this fix is not backported */
00180 /* ### These fixes should go into APR. */
00181 #ifndef WIN32
00182 #define SVN__APR_STATUS_IS_ENOTDIR(s)  APR_STATUS_IS_ENOTDIR(s)
00183 #else
00184 #define SVN__APR_STATUS_IS_ENOTDIR(s)  (APR_STATUS_IS_ENOTDIR(s) \
00185                       || ((s) == APR_OS_START_SYSERR + ERROR_DIRECTORY) \
00186                       || ((s) == APR_OS_START_SYSERR + ERROR_INVALID_NAME))
00187 #endif
00188 
00189 /** On Windows, APR_STATUS_IS_EPIPE does not include ERROR_NO_DATA error.
00190  * So we include it.*/
00191 /* ### These fixes should go into APR. */
00192 #ifndef WIN32
00193 #define SVN__APR_STATUS_IS_EPIPE(s)  APR_STATUS_IS_EPIPE(s)
00194 #else
00195 #define SVN__APR_STATUS_IS_EPIPE(s)  (APR_STATUS_IS_EPIPE(s) \
00196                       || ((s) == APR_OS_START_SYSERR + ERROR_NO_DATA))
00197 #endif
00198 
00199 /** @} */
00200 
00201 /** The various types of nodes in the Subversion filesystem. */
00202 typedef enum svn_node_kind_t
00203 {
00204   /** absent */
00205   svn_node_none,
00206 
00207   /** regular file */
00208   svn_node_file,
00209 
00210   /** directory */
00211   svn_node_dir,
00212 
00213   /** something's here, but we don't know what */
00214   svn_node_unknown
00215 } svn_node_kind_t;
00216 
00217 /** Return a constant string expressing @a kind as an English word, e.g.,
00218  * "file", "dir", etc.  The string is not localized, as it may be used for
00219  * client<->server communications.  If the kind is not recognized, return
00220  * "unknown".
00221  *
00222  * @since New in 1.6.
00223  */
00224 const char *
00225 svn_node_kind_to_word(svn_node_kind_t kind);
00226 
00227 /** Return the appropriate node_kind for @a word.  @a word is as
00228  * returned from svn_node_kind_to_word().  If @a word does not
00229  * represent a recognized kind or is @c NULL, return #svn_node_unknown.
00230  *
00231  * @since New in 1.6.
00232  */
00233 svn_node_kind_t
00234 svn_node_kind_from_word(const char *word);
00235 
00236 /** Generic three-state property to represent an unknown value for values
00237  * that are just like booleans.  The values have been set deliberately to
00238  * make tristates disjoint from #svn_boolean_t.
00239  *
00240  * @note It is unsafe to use apr_pcalloc() to allocate these, since '0' is
00241  * not a valid value.
00242  *
00243  * @since New in 1.7. */
00244 typedef enum svn_tristate_t
00245 {
00246   svn_tristate_false = 2,
00247   svn_tristate_true,
00248   svn_tristate_unknown
00249 } svn_tristate_t;
00250 
00251 /** Return a constant string "true", "false" or NULL representing the value of
00252  * @a tristate.
00253  *
00254  * @since New in 1.7.
00255  */
00256 const char *
00257 svn_tristate__to_word(svn_tristate_t tristate);
00258 
00259 /** Return the appropriate tristate for @a word. If @a word is "true", returns
00260  * #svn_tristate_true; if @a word is "false", returns #svn_tristate_false,
00261  * for all other values (including NULL) returns #svn_tristate_unknown.
00262  *
00263  * @since New in 1.7.
00264  */
00265 svn_tristate_t
00266 svn_tristate__from_word(const char * word);
00267 
00268 
00269 /** About Special Files in Subversion
00270  *
00271  * Subversion denotes files that cannot be portably created or
00272  * modified as "special" files (svn_node_special).  It stores these
00273  * files in the repository as a plain text file with the svn:special
00274  * property set.  The file contents contain: a platform-specific type
00275  * string, a space character, then any information necessary to create
00276  * the file on a supported platform.  For example, if a symbolic link
00277  * were being represented, the repository file would have the
00278  * following contents:
00279  *
00280  * "link /path/to/link/target"
00281  *
00282  * Where 'link' is the identifier string showing that this special
00283  * file should be a symbolic link and '/path/to/link/target' is the
00284  * destination of the symbolic link.
00285  *
00286  * Special files are stored in the text-base exactly as they are
00287  * stored in the repository.  The platform specific files are created
00288  * in the working copy at EOL/keyword translation time using
00289  * svn_subst_copy_and_translate2().  If the current platform does not
00290  * support a specific special file type, the file is copied into the
00291  * working copy as it is seen in the repository.  Because of this,
00292  * users of other platforms can still view and modify the special
00293  * files, even if they do not have their unique properties.
00294  *
00295  * New types of special files can be added by:
00296  *  1. Implementing a platform-dependent routine to create a uniquely
00297  *     named special file and one to read the special file in
00298  *     libsvn_subr/io.c.
00299  *  2. Creating a new textual name similar to
00300  *     SVN_SUBST__SPECIAL_LINK_STR in libsvn_subr/subst.c.
00301  *  3. Handling the translation/detranslation case for the new type in
00302  *     create_special_file and detranslate_special_file, using the
00303  *     routines from 1.
00304  */
00305 
00306 /** A revision number. */
00307 typedef long int svn_revnum_t;
00308 
00309 /** Valid revision numbers begin at 0 */
00310 #define SVN_IS_VALID_REVNUM(n) ((n) >= 0)
00311 
00312 /** The 'official' invalid revision num */
00313 #define SVN_INVALID_REVNUM ((svn_revnum_t) -1)
00314 
00315 /** Not really invalid...just unimportant -- one day, this can be its
00316  * own unique value, for now, just make it the same as
00317  * #SVN_INVALID_REVNUM.
00318  */
00319 #define SVN_IGNORED_REVNUM ((svn_revnum_t) -1)
00320 
00321 /** Convert NULL-terminated C string @a str to a revision number. */
00322 #define SVN_STR_TO_REV(str) ((svn_revnum_t) atol(str))
00323 
00324 /**
00325  * Parse NULL-terminated C string @a str as a revision number and
00326  * store its value in @a rev.  If @a endptr is non-NULL, then the
00327  * address of the first non-numeric character in @a str is stored in
00328  * it.  If there are no digits in @a str, then @a endptr is set (if
00329  * non-NULL), and the error #SVN_ERR_REVNUM_PARSE_FAILURE error is
00330  * returned.  Negative numbers parsed from @a str are considered
00331  * invalid, and result in the same error.
00332  *
00333  * @since New in 1.5.
00334  */
00335 svn_error_t *
00336 svn_revnum_parse(svn_revnum_t *rev,
00337                  const char *str,
00338                  const char **endptr);
00339 
00340 /** Originally intended to be used in printf()-style functions to format
00341  * revision numbers.  Deprecated due to incompatibilities with language
00342  * translation tools (e.g. gettext).
00343  *
00344  * New code should use a bare "%ld" format specifier for formatting revision
00345  * numbers.
00346  *
00347  * @deprecated Provided for backward compatibility with the 1.0 API.
00348  */
00349 #define SVN_REVNUM_T_FMT "ld"
00350 
00351 
00352 /** The size of a file in the Subversion FS. */
00353 typedef apr_int64_t svn_filesize_t;
00354 
00355 /** The 'official' invalid file size constant. */
00356 #define SVN_INVALID_FILESIZE ((svn_filesize_t) -1)
00357 
00358 /** In printf()-style functions, format file sizes using this. */
00359 #define SVN_FILESIZE_T_FMT APR_INT64_T_FMT
00360 
00361 #ifndef DOXYGEN_SHOULD_SKIP_THIS
00362 /* Parse a base-10 numeric string into a 64-bit unsigned numeric value. */
00363 /* NOTE: Private. For use by Subversion's own code only. See issue #1644. */
00364 /* FIXME: APR should supply a function to do this, such as "apr_atoui64". */
00365 #define svn__atoui64(X) ((apr_uint64_t) apr_atoi64(X))
00366 #endif
00367 
00368 
00369 /** YABT:  Yet Another Boolean Type */
00370 typedef int svn_boolean_t;
00371 
00372 #ifndef TRUE
00373 /** uhh... true */
00374 #define TRUE 1
00375 #endif /* TRUE */
00376 
00377 #ifndef FALSE
00378 /** uhh... false */
00379 #define FALSE 0
00380 #endif /* FALSE */
00381 
00382 
00383 /** An enum to indicate whether recursion is needed. */
00384 enum svn_recurse_kind
00385 {
00386   svn_nonrecursive = 1,
00387   svn_recursive
00388 };
00389 
00390 /** The concept of depth for directories.
00391  *
00392  * @note This is similar to, but not exactly the same as, the WebDAV
00393  * and LDAP concepts of depth.
00394  *
00395  * @since New in 1.5.
00396  */
00397 typedef enum svn_depth_t
00398 {
00399   /* The order of these depths is important: the higher the number,
00400      the deeper it descends.  This allows us to compare two depths
00401      numerically to decide which should govern. */
00402 
00403   /** Depth undetermined or ignored.  In some contexts, this means the
00404       client should choose an appropriate default depth.  The server
00405       will generally treat it as #svn_depth_infinity. */
00406   svn_depth_unknown    = -2,
00407 
00408   /** Exclude (i.e., don't descend into) directory D.
00409       @note In Subversion 1.5, svn_depth_exclude is *not* supported
00410       anywhere in the client-side (libsvn_wc/libsvn_client/etc) code;
00411       it is only supported as an argument to set_path functions in the
00412       ra and repos reporters.  (This will enable future versions of
00413       Subversion to run updates, etc, against 1.5 servers with proper
00414       svn_depth_exclude behavior, once we get a chance to implement
00415       client-side support for svn_depth_exclude.)
00416   */
00417   svn_depth_exclude    = -1,
00418 
00419   /** Just the named directory D, no entries.  Updates will not pull in
00420       any files or subdirectories not already present. */
00421   svn_depth_empty      =  0,
00422 
00423   /** D + its file children, but not subdirs.  Updates will pull in any
00424       files not already present, but not subdirectories. */
00425   svn_depth_files      =  1,
00426 
00427   /** D + immediate children (D and its entries).  Updates will pull in
00428       any files or subdirectories not already present; those
00429       subdirectories' this_dir entries will have depth-empty. */
00430   svn_depth_immediates =  2,
00431 
00432   /** D + all descendants (full recursion from D).  Updates will pull
00433       in any files or subdirectories not already present; those
00434       subdirectories' this_dir entries will have depth-infinity.
00435       Equivalent to the pre-1.5 default update behavior. */
00436   svn_depth_infinity   =  3
00437 
00438 } svn_depth_t;
00439 
00440 
00441 /** Return a constant string expressing @a depth as an English word,
00442  * e.g., "infinity", "immediates", etc.  The string is not localized,
00443  * as it may be used for client<->server communications.
00444  *
00445  * @since New in 1.5.
00446  */
00447 const char *
00448 svn_depth_to_word(svn_depth_t depth);
00449 
00450 
00451 /** Return the appropriate depth for @a depth_str.  @a word is as
00452  * returned from svn_depth_to_word().  If @a depth_str does not
00453  * represent a recognized depth, return #svn_depth_unknown.
00454  *
00455  * @since New in 1.5.
00456  */
00457 svn_depth_t
00458 svn_depth_from_word(const char *word);
00459 
00460 
00461 /* Return #svn_depth_infinity if boolean @a recurse is TRUE, else
00462  * return #svn_depth_files.
00463  *
00464  * @note New code should never need to use this, it is called only
00465  * from pre-depth APIs, for compatibility.
00466  *
00467  * @since New in 1.5.
00468  */
00469 #define SVN_DEPTH_INFINITY_OR_FILES(recurse) \
00470   ((recurse) ? svn_depth_infinity : svn_depth_files)
00471 
00472 
00473 /* Return #svn_depth_infinity if boolean @a recurse is TRUE, else
00474  * return #svn_depth_immediates.
00475  *
00476  * @note New code should never need to use this, it is called only
00477  * from pre-depth APIs, for compatibility.
00478  *
00479  * @since New in 1.5.
00480  */
00481 #define SVN_DEPTH_INFINITY_OR_IMMEDIATES(recurse) \
00482   ((recurse) ? svn_depth_infinity : svn_depth_immediates)
00483 
00484 
00485 /* Return #svn_depth_infinity if boolean @a recurse is TRUE, else
00486  * return #svn_depth_empty.
00487  *
00488  * @note New code should never need to use this, it is called only
00489  * from pre-depth APIs, for compatibility.
00490  *
00491  * @since New in 1.5.
00492  */
00493 #define SVN_DEPTH_INFINITY_OR_EMPTY(recurse) \
00494   ((recurse) ? svn_depth_infinity : svn_depth_empty)
00495 
00496 
00497 /* Return a recursion boolean based on @a depth.
00498  *
00499  * Although much code has been converted to use depth, some code still
00500  * takes a recurse boolean.  In most cases, it makes sense to treat
00501  * unknown or infinite depth as recursive, and any other depth as
00502  * non-recursive (which in turn usually translates to #svn_depth_files).
00503  */
00504 #define SVN_DEPTH_IS_RECURSIVE(depth)                              \
00505   (((depth) == svn_depth_infinity || (depth) == svn_depth_unknown) \
00506    ? TRUE : FALSE)
00507 
00508 
00509 /**
00510  * It is sometimes convenient to indicate which parts of an #svn_dirent_t
00511  * object you are actually interested in, so that calculating and sending
00512  * the data corresponding to the other fields can be avoided.  These values
00513  * can be used for that purpose.
00514  *
00515  * @defgroup svn_dirent_fields Dirent fields
00516  * @{
00517  */
00518 
00519 /** An indication that you are interested in the @c kind field */
00520 #define SVN_DIRENT_KIND        0x00001
00521 
00522 /** An indication that you are interested in the @c size field */
00523 #define SVN_DIRENT_SIZE        0x00002
00524 
00525 /** An indication that you are interested in the @c has_props field */
00526 #define SVN_DIRENT_HAS_PROPS   0x00004
00527 
00528 /** An indication that you are interested in the @c created_rev field */
00529 #define SVN_DIRENT_CREATED_REV 0x00008
00530 
00531 /** An indication that you are interested in the @c time field */
00532 #define SVN_DIRENT_TIME        0x00010
00533 
00534 /** An indication that you are interested in the @c last_author field */
00535 #define SVN_DIRENT_LAST_AUTHOR 0x00020
00536 
00537 /** A combination of all the dirent fields */
00538 #define SVN_DIRENT_ALL ~((apr_uint32_t ) 0)
00539 
00540 /** @} */
00541 
00542 /** A general subversion directory entry. */
00543 typedef struct svn_dirent_t
00544 {
00545   /** node kind */
00546   svn_node_kind_t kind;
00547 
00548   /** length of file text, or 0 for directories */
00549   svn_filesize_t size;
00550 
00551   /** does the node have props? */
00552   svn_boolean_t has_props;
00553 
00554   /** last rev in which this node changed */
00555   svn_revnum_t created_rev;
00556 
00557   /** time of created_rev (mod-time) */
00558   apr_time_t time;
00559 
00560   /** author of created_rev */
00561   const char *last_author;
00562 
00563   /* IMPORTANT: If you extend this struct, check svn_dirent_dup(). */
00564 } svn_dirent_t;
00565 
00566 
00567 /** Return a deep copy of @a dirent, allocated in @a pool.
00568  *
00569  * @since New in 1.4.
00570  */
00571 svn_dirent_t *
00572 svn_dirent_dup(const svn_dirent_t *dirent,
00573                apr_pool_t *pool);
00574 
00575 
00576 
00577 /** Keyword substitution.
00578  *
00579  * All the keywords Subversion recognizes.
00580  *
00581  * Note that there is a better, more general proposal out there, which
00582  * would take care of both internationalization issues and custom
00583  * keywords (e.g., $NetBSD$).  See
00584  *
00585  * @verbatim
00586       http://subversion.tigris.org/servlets/ReadMsg?list=dev&msgNo=8921
00587       =====
00588       From: "Jonathan M. Manning" <jmanning@alisa-jon.net>
00589       To: dev@subversion.tigris.org
00590       Date: Fri, 14 Dec 2001 11:56:54 -0500
00591       Message-ID: <87970000.1008349014@bdldevel.bl.bdx.com>
00592       Subject: Re: keywords @endverbatim
00593  *
00594  * and Eric Gillespie's support of same:
00595  *
00596  * @verbatim
00597       http://subversion.tigris.org/servlets/ReadMsg?list=dev&msgNo=8757
00598       =====
00599       From: "Eric Gillespie, Jr." <epg@pretzelnet.org>
00600       To: dev@subversion.tigris.org
00601       Date: Wed, 12 Dec 2001 09:48:42 -0500
00602       Message-ID: <87k7vsebp1.fsf@vger.pretzelnet.org>
00603       Subject: Re: Customizable Keywords @endverbatim
00604  *
00605  * However, it is considerably more complex than the scheme below.
00606  * For now we're going with simplicity, hopefully the more general
00607  * solution can be done post-1.0.
00608  *
00609  * @defgroup svn_types_keywords Keyword definitions
00610  * @{
00611  */
00612 
00613 /** The maximum size of an expanded or un-expanded keyword. */
00614 #define SVN_KEYWORD_MAX_LEN    255
00615 
00616 /** The most recent revision in which this file was changed. */
00617 #define SVN_KEYWORD_REVISION_LONG    "LastChangedRevision"
00618 
00619 /** Short version of LastChangedRevision */
00620 #define SVN_KEYWORD_REVISION_SHORT   "Rev"
00621 
00622 /** Medium version of LastChangedRevision, matching the one CVS uses.
00623  * @since New in 1.1. */
00624 #define SVN_KEYWORD_REVISION_MEDIUM  "Revision"
00625 
00626 /** The most recent date (repository time) when this file was changed. */
00627 #define SVN_KEYWORD_DATE_LONG        "LastChangedDate"
00628 
00629 /** Short version of LastChangedDate */
00630 #define SVN_KEYWORD_DATE_SHORT       "Date"
00631 
00632 /** Who most recently committed to this file. */
00633 #define SVN_KEYWORD_AUTHOR_LONG      "LastChangedBy"
00634 
00635 /** Short version of LastChangedBy */
00636 #define SVN_KEYWORD_AUTHOR_SHORT     "Author"
00637 
00638 /** The URL for the head revision of this file. */
00639 #define SVN_KEYWORD_URL_LONG         "HeadURL"
00640 
00641 /** Short version of HeadURL */
00642 #define SVN_KEYWORD_URL_SHORT        "URL"
00643 
00644 /** A compressed combination of the other four keywords. */
00645 #define SVN_KEYWORD_ID               "Id"
00646 
00647 /** A full combination of the first four keywords.
00648  * @since New in 1.6. */
00649 #define SVN_KEYWORD_HEADER           "Header"
00650 
00651 /** @} */
00652 
00653 
00654 /** All information about a commit.
00655  *
00656  * @note Objects of this type should always be created using the
00657  * svn_create_commit_info() function.
00658  *
00659  * @since New in 1.3.
00660  */
00661 typedef struct svn_commit_info_t
00662 {
00663   /** just-committed revision. */
00664   svn_revnum_t revision;
00665 
00666   /** server-side date of the commit. */
00667   const char *date;
00668 
00669   /** author of the commit. */
00670   const char *author;
00671 
00672   /** error message from post-commit hook, or NULL. */
00673   const char *post_commit_err;
00674 
00675   /** repository root, may be @c NULL if unknown.
00676       @since New in 1.7. */
00677   const char *repos_root;
00678 
00679 } svn_commit_info_t;
00680 
00681 
00682 /**
00683  * Allocate an object of type #svn_commit_info_t in @a pool and
00684  * return it.
00685  *
00686  * The @c revision field of the new struct is set to #SVN_INVALID_REVNUM.
00687  * All other fields are initialized to @c NULL.
00688  *
00689  * @note Any object of the type #svn_commit_info_t should
00690  * be created using this function.
00691  * This is to provide for extending the svn_commit_info_t in
00692  * the future.
00693  *
00694  * @since New in 1.3.
00695  */
00696 svn_commit_info_t *
00697 svn_create_commit_info(apr_pool_t *pool);
00698 
00699 
00700 /**
00701  * Return a deep copy @a src_commit_info allocated in @a pool.
00702  *
00703  * @since New in 1.4.
00704  */
00705 svn_commit_info_t *
00706 svn_commit_info_dup(const svn_commit_info_t *src_commit_info,
00707                     apr_pool_t *pool);
00708 
00709 
00710 /**
00711  * A structure to represent a path that changed for a log entry.
00712  *
00713  * @note To allow for extending the #svn_log_changed_path2_t structure in
00714  * future releases, always use svn_log_changed_path2_create() to allocate
00715  * the structure.
00716  *
00717  * @since New in 1.6.
00718  */
00719 typedef struct svn_log_changed_path2_t
00720 {
00721   /** 'A'dd, 'D'elete, 'R'eplace, 'M'odify */
00722   char action;
00723 
00724   /** Source path of copy (if any). */
00725   const char *copyfrom_path;
00726 
00727   /** Source revision of copy (if any). */
00728   svn_revnum_t copyfrom_rev;
00729 
00730   /** The type of the node, may be svn_node_unknown. */
00731   svn_node_kind_t node_kind;
00732 
00733   /** Is the text modified, may be svn_tristate_unknown.
00734    * @since New in 1.7. */
00735   svn_tristate_t text_modified;
00736 
00737   /** Are properties modified, may be svn_tristate_unknown.
00738    * @since New in 1.7. */
00739   svn_tristate_t props_modified;
00740 
00741   /* NOTE: Add new fields at the end to preserve binary compatibility.
00742      Also, if you add fields here, you have to update
00743      svn_log_changed_path2_dup(). */
00744 } svn_log_changed_path2_t;
00745 
00746 /**
00747  * Returns an #svn_log_changed_path2_t, allocated in @a pool with all fields
00748  * initialized to NULL, None or empty values.
00749  *
00750  * @note To allow for extending the #svn_log_changed_path2_t structure in
00751  * future releases, this function should always be used to allocate the
00752  * structure.
00753  *
00754  * @since New in 1.6.
00755  */
00756 svn_log_changed_path2_t *
00757 svn_log_changed_path2_create(apr_pool_t *pool);
00758 
00759 /**
00760  * Return a deep copy of @a changed_path, allocated in @a pool.
00761  *
00762  * @since New in 1.6.
00763  */
00764 svn_log_changed_path2_t *
00765 svn_log_changed_path2_dup(const svn_log_changed_path2_t *changed_path,
00766                           apr_pool_t *pool);
00767 
00768 /**
00769  * A structure to represent a path that changed for a log entry.  Same as
00770  * #svn_log_changed_path2_t, but without the node kind.
00771  *
00772  * @deprecated Provided for backward compatibility with the 1.5 API.
00773  */
00774 typedef struct svn_log_changed_path_t
00775 {
00776   /** 'A'dd, 'D'elete, 'R'eplace, 'M'odify */
00777   char action;
00778 
00779   /** Source path of copy (if any). */
00780   const char *copyfrom_path;
00781 
00782   /** Source revision of copy (if any). */
00783   svn_revnum_t copyfrom_rev;
00784 
00785 } svn_log_changed_path_t;
00786 
00787 
00788 /**
00789  * Return a deep copy of @a changed_path, allocated in @a pool.
00790  *
00791  * @since New in 1.3.
00792  * @deprecated Provided for backward compatibility with the 1.5 API.
00793  */
00794 SVN_DEPRECATED
00795 svn_log_changed_path_t *
00796 svn_log_changed_path_dup(const svn_log_changed_path_t *changed_path,
00797                          apr_pool_t *pool);
00798 
00799 /**
00800  * A structure to represent all the information about a particular log entry.
00801  *
00802  * @note To allow for extending the #svn_log_entry_t structure in future
00803  * releases, always use svn_log_entry_create() to allocate the structure.
00804  *
00805  * @since New in 1.5.
00806  */
00807 typedef struct svn_log_entry_t
00808 {
00809   /** A hash containing as keys every path committed in @a revision; the
00810    * values are (#svn_log_changed_path_t *) structures.
00811    *
00812    * The subversion core libraries will always set this field to the same
00813    * value as changed_paths2 for compatibility reasons.
00814    *
00815    * @deprecated Provided for backward compatibility with the 1.5 API.
00816    */
00817   apr_hash_t *changed_paths;
00818 
00819   /** The revision of the commit. */
00820   svn_revnum_t revision;
00821 
00822   /** The hash of requested revision properties, which may be NULL if it
00823    * would contain no revprops. */
00824   apr_hash_t *revprops;
00825 
00826   /**
00827    * Whether or not this message has children.
00828    *
00829    * When a log operation requests additional merge information, extra log
00830    * entries may be returned as a result of this entry.  The new entries, are
00831    * considered children of the original entry, and will follow it.  When
00832    * the HAS_CHILDREN flag is set, the receiver should increment its stack
00833    * depth, and wait until an entry is provided with SVN_INVALID_REVNUM which
00834    * indicates the end of the children.
00835    *
00836    * For log operations which do not request additional merge information, the
00837    * HAS_CHILDREN flag is always FALSE.
00838    *
00839    * For more information see:
00840    * https://svn.apache.org/repos/asf/subversion/trunk/notes/merge-tracking/design.html#commutative-reporting
00841    */
00842   svn_boolean_t has_children;
00843 
00844   /** A hash containing as keys every path committed in @a revision; the
00845    * values are (#svn_log_changed_path2_t *) structures.
00846    *
00847    * If this value is not @c NULL, it MUST have the same value as
00848    * changed_paths or svn_log_entry_dup() will not create an identical copy.
00849    *
00850    * The subversion core libraries will always set this field to the same
00851    * value as changed_paths for compatibility with users assuming an older
00852    * version.
00853    *
00854    * @note See http://svn.haxx.se/dev/archive-2010-08/0362.shtml for
00855    * further explanation.
00856    *
00857    * @since New in 1.6.
00858    */
00859   apr_hash_t *changed_paths2;
00860 
00861   /**
00862    * Whether @a revision should be interpreted as non-inheritable in the
00863    * same sense of #svn_merge_range_t.
00864    *
00865    * @since New in 1.7.
00866    */
00867   svn_boolean_t non_inheritable;
00868 
00869   /**
00870    * Whether @a revision is a merged revision resulting from a reverse merge.
00871    *
00872    * @since New in 1.7.
00873    */
00874   svn_boolean_t subtractive_merge;
00875 
00876   /* NOTE: Add new fields at the end to preserve binary compatibility.
00877      Also, if you add fields here, you have to update
00878      svn_log_entry_dup(). */
00879 } svn_log_entry_t;
00880 
00881 /**
00882  * Returns an #svn_log_entry_t, allocated in @a pool with all fields
00883  * initialized to NULL values.
00884  *
00885  * @note To allow for extending the #svn_log_entry_t structure in future
00886  * releases, this function should always be used to allocate the structure.
00887  *
00888  * @since New in 1.5.
00889  */
00890 svn_log_entry_t *
00891 svn_log_entry_create(apr_pool_t *pool);
00892 
00893 /** Return a deep copy of @a log_entry, allocated in @a pool.
00894  *
00895  * The resulting svn_log_entry_t has @c changed_paths set to the same
00896  * value as @c changed_path2. @c changed_paths will be @c NULL if
00897  * @c changed_paths2 was @c NULL.
00898  *
00899  * @since New in 1.6.
00900  */
00901 svn_log_entry_t *
00902 svn_log_entry_dup(const svn_log_entry_t *log_entry, apr_pool_t *pool);
00903 
00904 /** The callback invoked by log message loopers, such as
00905  * #svn_ra_plugin_t.get_log() and svn_repos_get_logs().
00906  *
00907  * This function is invoked once on each log message, in the order
00908  * determined by the caller (see above-mentioned functions).
00909  *
00910  * @a baton is what you think it is, and @a log_entry contains relevant
00911  * information for the log message.  Any of @a log_entry->author,
00912  * @a log_entry->date, or @a log_entry->message may be @c NULL.
00913  *
00914  * If @a log_entry->date is neither NULL nor the empty string, it was
00915  * generated by svn_time_to_cstring() and can be converted to
00916  * @c apr_time_t with svn_time_from_cstring().
00917  *
00918  * If @a log_entry->changed_paths is non-@c NULL, then it contains as keys
00919  * every path committed in @a log_entry->revision; the values are
00920  * (#svn_log_changed_path_t *) structures.
00921  *
00922  * If @a log_entry->has_children is @c TRUE, the message will be followed
00923  * immediately by any number of merged revisions (child messages), which are
00924  * terminated by an invocation with SVN_INVALID_REVNUM.  This usage may
00925  * be recursive.
00926  *
00927  * Use @a pool for temporary allocation.  If the caller is iterating
00928  * over log messages, invoking this receiver on each, we recommend the
00929  * standard pool loop recipe: create a subpool, pass it as @a pool to
00930  * each call, clear it after each iteration, destroy it after the loop
00931  * is done.  (For allocation that must last beyond the lifetime of a
00932  * given receiver call, use a pool in @a baton.)
00933  *
00934  * @since New in 1.5.
00935  */
00936 
00937 typedef svn_error_t *(*svn_log_entry_receiver_t)(
00938   void *baton,
00939   svn_log_entry_t *log_entry,
00940   apr_pool_t *pool);
00941 
00942 /**
00943  * Similar to #svn_log_entry_receiver_t, except this uses separate
00944  * parameters for each part of the log entry.
00945  *
00946  * @deprecated Provided for backward compatibility with the 1.4 API.
00947  */
00948 typedef svn_error_t *(*svn_log_message_receiver_t)(
00949   void *baton,
00950   apr_hash_t *changed_paths,
00951   svn_revnum_t revision,
00952   const char *author,
00953   const char *date,  /* use svn_time_from_cstring() if need apr_time_t */
00954   const char *message,
00955   apr_pool_t *pool);
00956 
00957 
00958 /** Callback function type for commits.
00959  *
00960  * When a commit succeeds, an instance of this is invoked with the
00961  * @a commit_info, along with the @a baton closure.
00962  * @a pool can be used for temporary allocations.
00963  *
00964  * @since New in 1.4.
00965  */
00966 typedef svn_error_t *(*svn_commit_callback2_t)(
00967   const svn_commit_info_t *commit_info,
00968   void *baton,
00969   apr_pool_t *pool);
00970 
00971 /** Same as #svn_commit_callback2_t, but uses individual
00972  * data elements instead of the #svn_commit_info_t structure
00973  *
00974  * @deprecated Provided for backward compatibility with the 1.3 API.
00975  */
00976 typedef svn_error_t *(*svn_commit_callback_t)(
00977   svn_revnum_t new_revision,
00978   const char *date,
00979   const char *author,
00980   void *baton);
00981 
00982 
00983 /** A buffer size that may be used when processing a stream of data.
00984  *
00985  * @note We don't use this constant any longer, since it is considered to be
00986  * unnecessarily large.
00987  *
00988  * @deprecated Provided for backwards compatibility with the 1.3 API.
00989  */
00990 #define SVN_STREAM_CHUNK_SIZE 102400
00991 
00992 #ifndef DOXYGEN_SHOULD_SKIP_THIS
00993 /*
00994  * The maximum amount we (ideally) hold in memory at a time when
00995  * processing a stream of data.
00996  *
00997  * For example, when copying data from one stream to another, do it in
00998  * blocks of this size.
00999  *
01000  * NOTE: This is an internal macro, put here for convenience.
01001  * No public API may depend on the particular value of this macro.
01002  */
01003 #define SVN__STREAM_CHUNK_SIZE 16384
01004 #endif
01005 
01006 /** The maximum amount we can ever hold in memory. */
01007 /* FIXME: Should this be the same as SVN_STREAM_CHUNK_SIZE? */
01008 #define SVN_MAX_OBJECT_SIZE (((apr_size_t) -1) / 2)
01009 
01010 
01011 
01012 /* ### Note: despite being about mime-TYPES, these probably don't
01013  * ### belong in svn_types.h.  However, no other header is more
01014  * ### appropriate, and didn't feel like creating svn_validate.h for
01015  * ### so little.
01016  */
01017 
01018 /** Validate @a mime_type.
01019  *
01020  * If @a mime_type does not contain a "/", or ends with non-alphanumeric
01021  * data, return #SVN_ERR_BAD_MIME_TYPE, else return success.
01022  *
01023  * Use @a pool only to find error allocation.
01024  *
01025  * Goal: to match both "foo/bar" and "foo/bar; charset=blah", without
01026  * being too strict about it, but to disallow mime types that have
01027  * quotes, newlines, or other garbage on the end, such as might be
01028  * unsafe in an HTTP header.
01029  */
01030 svn_error_t *
01031 svn_mime_type_validate(const char *mime_type,
01032                        apr_pool_t *pool);
01033 
01034 
01035 /** Return FALSE iff @a mime_type is a textual type.
01036  *
01037  * All mime types that start with "text/" are textual, plus some special
01038  * cases (for example, "image/x-xbitmap").
01039  */
01040 svn_boolean_t
01041 svn_mime_type_is_binary(const char *mime_type);
01042 
01043 
01044 
01045 /** A user defined callback that subversion will call with a user defined
01046  * baton to see if the current operation should be continued.  If the operation
01047  * should continue, the function should return #SVN_NO_ERROR, if not, it
01048  * should return #SVN_ERR_CANCELLED.
01049  */
01050 typedef svn_error_t *(*svn_cancel_func_t)(void *cancel_baton);
01051 
01052 
01053 
01054 /**
01055  * A lock object, for client & server to share.
01056  *
01057  * A lock represents the exclusive right to add, delete, or modify a
01058  * path.  A lock is created in a repository, wholly controlled by the
01059  * repository.  A "lock-token" is the lock's UUID, and can be used to
01060  * learn more about a lock's fields, and or/make use of the lock.
01061  * Because a lock is immutable, a client is free to not only cache the
01062  * lock-token, but the lock's fields too, for convenience.
01063  *
01064  * Note that the 'is_dav_comment' field is wholly ignored by every
01065  * library except for mod_dav_svn.  The field isn't even marshalled
01066  * over the network to the client.  Assuming lock structures are
01067  * created with apr_pcalloc(), a default value of 0 is universally safe.
01068  *
01069  * @note in the current implementation, only files are lockable.
01070  *
01071  * @since New in 1.2.
01072  */
01073 typedef struct svn_lock_t
01074 {
01075   const char *path;              /**< the path this lock applies to */
01076   const char *token;             /**< unique URI representing lock */
01077   const char *owner;             /**< the username which owns the lock */
01078   const char *comment;           /**< (optional) description of lock  */
01079   svn_boolean_t is_dav_comment;  /**< was comment made by generic DAV client? */
01080   apr_time_t creation_date;      /**< when lock was made */
01081   apr_time_t expiration_date;    /**< (optional) when lock will expire;
01082                                       If value is 0, lock will never expire. */
01083 } svn_lock_t;
01084 
01085 /**
01086  * Returns an #svn_lock_t, allocated in @a pool with all fields initialized
01087  * to NULL values.
01088  *
01089  * @note To allow for extending the #svn_lock_t structure in the future
01090  * releases, this function should always be used to allocate the structure.
01091  *
01092  * @since New in 1.2.
01093  */
01094 svn_lock_t *
01095 svn_lock_create(apr_pool_t *pool);
01096 
01097 /**
01098  * Return a deep copy of @a lock, allocated in @a pool.
01099  *
01100  * @since New in 1.2.
01101  */
01102 svn_lock_t *
01103 svn_lock_dup(const svn_lock_t *lock, apr_pool_t *pool);
01104 
01105 /**
01106  * Return a formatted Universal Unique IDentifier (UUID) string.
01107  *
01108  * @since New in 1.4.
01109  */
01110 const char *
01111 svn_uuid_generate(apr_pool_t *pool);
01112 
01113 /**
01114  * Mergeinfo representing a merge of a range of revisions.
01115  *
01116  * @since New in 1.5
01117  */
01118 typedef struct svn_merge_range_t
01119 {
01120   /**
01121    * If the 'start' field is less than the 'end' field then 'start' is
01122    * exclusive and 'end' inclusive of the range described.  This is termed
01123    * a forward merge range.  If 'start' is greater than 'end' then the
01124    * opposite is true.  This is termed a reverse merge range.  If 'start'
01125    * equals 'end' the meaning of the range is not defined.
01126    */
01127   svn_revnum_t start;
01128   svn_revnum_t end;
01129 
01130   /**
01131    * Whether this merge range should be inherited by treewise
01132    * descendants of the path to which the range applies. */
01133   svn_boolean_t inheritable;
01134 } svn_merge_range_t;
01135 
01136 /**
01137  * Return a copy of @a range, allocated in @a pool.
01138  *
01139  * @since New in 1.5.
01140  */
01141 svn_merge_range_t *
01142 svn_merge_range_dup(const svn_merge_range_t *range, apr_pool_t *pool);
01143 
01144 /**
01145  * Returns true if the changeset committed in revision @a rev is one
01146  * of the changesets in the range @a range.
01147  *
01148  * @since New in 1.5.
01149  */
01150 svn_boolean_t
01151 svn_merge_range_contains_rev(const svn_merge_range_t *range, svn_revnum_t rev);
01152 
01153 
01154 
01155 /** @defgroup node_location_seg_reporting Node location segment reporting.
01156  *  @{ */
01157 
01158 /**
01159  * A representation of a segment of a object's version history with an
01160  * emphasis on the object's location in the repository as of various
01161  * revisions.
01162  *
01163  * @since New in 1.5.
01164  */
01165 typedef struct svn_location_segment_t
01166 {
01167   /** The beginning (oldest) and ending (youngest) revisions for this
01168       segment. */
01169   svn_revnum_t range_start;
01170   svn_revnum_t range_end;
01171 
01172   /** The absolute (sans leading slash) path for this segment.  May be
01173       NULL to indicate gaps in an object's history.  */
01174   const char *path;
01175 
01176 } svn_location_segment_t;
01177 
01178 
01179 /**
01180  * A callback invoked by generators of #svn_location_segment_t
01181  * objects, used to report information about a versioned object's
01182  * history in terms of its location in the repository filesystem over
01183  * time.
01184  */
01185 typedef svn_error_t *(*svn_location_segment_receiver_t)(
01186   svn_location_segment_t *segment,
01187   void *baton,
01188   apr_pool_t *pool);
01189 
01190 
01191 /**
01192  * Return a deep copy of @a segment, allocated in @a pool.
01193  *
01194  * @since New in 1.5.
01195  */
01196 svn_location_segment_t *
01197 svn_location_segment_dup(const svn_location_segment_t *segment,
01198                          apr_pool_t *pool);
01199 
01200 /** @} */
01201 
01202 /** A line number, such as in a file or a stream.
01203  *
01204  * @since New in 1.7.
01205  */
01206 typedef unsigned long svn_linenum_t;
01207 
01208 /* The maximum value of an svn_linenum_t.
01209  *
01210  * @since New in 1.7.
01211  */
01212 #define SVN_LINENUM_MAX_VALUE ULONG_MAX
01213 
01214 
01215 #ifdef __cplusplus
01216 }
01217 #endif /* __cplusplus */
01218 
01219 
01220 /*
01221  * Everybody and their brother needs to deal with svn_error_t, the error
01222  * codes, and whatever else. While they *should* go and include svn_error.h
01223  * in order to do that... bah. Let's just help everybody out and include
01224  * that header whenever somebody grabs svn_types.h.
01225  *
01226  * Note that we do this at the END of this header so that its contents
01227  * are available to svn_error.h (our guards will prevent the circular
01228  * include). We also need to do the include *outside* of the cplusplus
01229  * guard.
01230  */
01231 #include "svn_error.h"
01232 
01233 
01234 /*
01235  * Subversion developers may want to use some additional debugging facilities
01236  * while working on the code. We'll pull that in here, so individual source
01237  * files don't have to include this header manually.
01238  */
01239 #ifdef SVN_DEBUG
01240 #include "private/svn_debug.h"
01241 #endif
01242 
01243 
01244 #endif /* SVN_TYPES_H */
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines