Subversion 1.6.16

svn_types.h

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