3 * ====================================================================
4 * Licensed to the Apache Software Foundation (ASF) under one
5 * or more contributor license agreements. See the NOTICE file
6 * distributed with this work for additional information
7 * regarding copyright ownership. The ASF licenses this file
8 * to you under the Apache License, Version 2.0 (the
9 * "License"); you may not use this file except in compliance
10 * with the License. You may obtain a copy of the License at
12 * http://www.apache.org/licenses/LICENSE-2.0
14 * Unless required by applicable law or agreed to in writing,
15 * software distributed under the License is distributed on an
16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17 * KIND, either express or implied. See the License for the
18 * specific language governing permissions and limitations
20 * ====================================================================
24 * @brief Subversion's data types
30 /* ### this should go away, but it causes too much breakage right now */
32 #include <limits.h> /* for ULONG_MAX */
34 #include <apr.h> /* for apr_size_t, apr_int64_t, ... */
35 #include <apr_errno.h> /* for apr_status_t */
36 #include <apr_pools.h> /* for apr_pool_t */
37 #include <apr_hash.h> /* for apr_hash_t */
38 #include <apr_tables.h> /* for apr_array_push() */
39 #include <apr_time.h> /* for apr_time_t */
40 #include <apr_strings.h> /* for apr_atoi64() */
44 #endif /* __cplusplus */
48 /** Macro used to mark deprecated functions.
52 #ifndef SVN_DEPRECATED
53 # if !defined(SWIGPERL) && !defined(SWIGPYTHON) && !defined(SWIGRUBY)
54 # if defined(__GNUC__) && (__GNUC__ >= 4 || (__GNUC__==3 && __GNUC_MINOR__>=1))
55 # define SVN_DEPRECATED __attribute__((deprecated))
56 # elif defined(_MSC_VER) && _MSC_VER >= 1300
57 # define SVN_DEPRECATED __declspec(deprecated)
59 # define SVN_DEPRECATED
62 # define SVN_DEPRECATED
67 /** Indicate whether the current platform supports unaligned data access.
69 * On the majority of machines running SVN (x86 / x64), unaligned access
70 * is much cheaper than repeated aligned access. Define this macro to 1
72 * Unaligned access on other machines (e.g. IA64) will trigger memory
73 * access faults or simply misbehave.
75 * Note: Some platforms may only support unaligned access for integers
76 * (PowerPC). As a result this macro should only be used to determine
77 * if unaligned access is supported for integers.
81 #ifndef SVN_UNALIGNED_ACCESS_IS_OK
82 # if defined(_M_IX86) || defined(i386) \
83 || defined(_M_X64) || defined(__x86_64) \
84 || defined(__powerpc__) || defined(__ppc__)
85 # define SVN_UNALIGNED_ACCESS_IS_OK 1
87 # define SVN_UNALIGNED_ACCESS_IS_OK 0
93 /** YABT: Yet Another Boolean Type */
94 typedef int svn_boolean_t;
108 /** Subversion error object.
110 * Defined here, rather than in svn_error.h, to avoid a recursive @#include
113 typedef struct svn_error_t
115 /** APR error value; possibly an SVN_ custom error code (see
116 * `svn_error_codes.h' for a full listing).
118 apr_status_t apr_err;
120 /** Details from the producer of error.
122 * Note that if this error was generated by Subversion's API, you'll
123 * probably want to use svn_err_best_message() to get a single
124 * descriptive string for this error chain (see the @a child member)
125 * or svn_handle_error2() to print the error chain in full. This is
126 * because Subversion's API functions sometimes add many links to
127 * the error chain that lack details (used only to produce virtual
128 * stack traces). (Use svn_error_purge_tracing() to remove those
129 * trace-only links from the error chain.)
133 /** Pointer to the error we "wrap" (may be @c NULL). Via this
134 * member, individual error object can be strung together into an
137 struct svn_error_t *child;
139 /** The pool in which this error object is allocated. (If
140 * Subversion's APIs are used to manage error chains, then this pool
141 * will contain the whole error chain of which this object is a
145 /** Source file where the error originated (iff @c SVN_DEBUG;
146 * undefined otherwise).
150 /** Source line where the error originated (iff @c SVN_DEBUG;
151 * undefined otherwise).
159 /* See svn_version.h.
160 Defined here to avoid including svn_version.h from all public headers. */
161 typedef struct svn_version_t svn_version_t;
165 /** @defgroup APR_ARRAY_compat_macros APR Array Compatibility Helper Macros
166 * These macros are provided by APR itself from version 1.3.
167 * Definitions are provided here for when using older versions of APR.
171 /** index into an apr_array_header_t */
172 #ifndef APR_ARRAY_IDX
173 #define APR_ARRAY_IDX(ary,i,type) (((type *)(ary)->elts)[i])
176 /** easier array-pushing syntax */
177 #ifndef APR_ARRAY_PUSH
178 #define APR_ARRAY_PUSH(ary,type) (*((type *)apr_array_push(ary)))
185 /** @defgroup apr_hash_utilities APR Hash Table Helpers
186 * These functions enable the caller to dereference an APR hash table index
187 * without type casts or temporary variables.
189 * ### These are private, and may go away when APR implements them natively.
193 /** Return the key of the hash table entry indexed by @a hi. */
195 svn__apr_hash_index_key(const apr_hash_index_t *hi);
197 /** Return the key length of the hash table entry indexed by @a hi. */
199 svn__apr_hash_index_klen(const apr_hash_index_t *hi);
201 /** Return the value of the hash table entry indexed by @a hi. */
203 svn__apr_hash_index_val(const apr_hash_index_t *hi);
209 /** On Windows, APR_STATUS_IS_ENOTDIR includes several kinds of
210 * invalid-pathname error but not ERROR_INVALID_NAME, so we include it.
211 * We also include ERROR_DIRECTORY as that was not included in apr versions
212 * before 1.4.0 and this fix is not backported */
213 /* ### These fixes should go into APR. */
215 #define SVN__APR_STATUS_IS_ENOTDIR(s) APR_STATUS_IS_ENOTDIR(s)
217 #define SVN__APR_STATUS_IS_ENOTDIR(s) (APR_STATUS_IS_ENOTDIR(s) \
218 || ((s) == APR_OS_START_SYSERR + ERROR_DIRECTORY) \
219 || ((s) == APR_OS_START_SYSERR + ERROR_INVALID_NAME))
222 /** On Windows, APR_STATUS_IS_EPIPE does not include ERROR_NO_DATA error.
223 * So we include it.*/
224 /* ### These fixes should go into APR. */
226 #define SVN__APR_STATUS_IS_EPIPE(s) APR_STATUS_IS_EPIPE(s)
228 #define SVN__APR_STATUS_IS_EPIPE(s) (APR_STATUS_IS_EPIPE(s) \
229 || ((s) == APR_OS_START_SYSERR + ERROR_NO_DATA))
236 /** The various types of nodes in the Subversion filesystem. */
237 typedef enum svn_node_kind_t
248 /** something's here, but we don't know what */
253 * @note This value is not currently used by the public API.
259 /** Return a constant string expressing @a kind as an English word, e.g.,
260 * "file", "dir", etc. The string is not localized, as it may be used for
261 * client<->server communications. If the kind is not recognized, return
267 svn_node_kind_to_word(svn_node_kind_t kind);
269 /** Return the appropriate node_kind for @a word. @a word is as
270 * returned from svn_node_kind_to_word(). If @a word does not
271 * represent a recognized kind or is @c NULL, return #svn_node_unknown.
276 svn_node_kind_from_word(const char *word);
279 /** Generic three-state property to represent an unknown value for values
280 * that are just like booleans. The values have been set deliberately to
281 * make tristates disjoint from #svn_boolean_t.
283 * @note It is unsafe to use apr_pcalloc() to allocate these, since '0' is
286 * @since New in 1.7. */
287 typedef enum svn_tristate_t
289 /** state known to be false (the constant does not evaulate to false) */
290 svn_tristate_false = 2,
291 /** state known to be true */
293 /** state could be true or false */
297 /** Return a constant string "true", "false" or NULL representing the value of
303 svn_tristate__to_word(svn_tristate_t tristate);
305 /** Return the appropriate tristate for @a word. If @a word is "true", returns
306 * #svn_tristate_true; if @a word is "false", returns #svn_tristate_false,
307 * for all other values (including NULL) returns #svn_tristate_unknown.
312 svn_tristate__from_word(const char * word);
316 /** About Special Files in Subversion
318 * Subversion denotes files that cannot be portably created or
319 * modified as "special" files (svn_node_special). It stores these
320 * files in the repository as a plain text file with the svn:special
321 * property set. The file contents contain: a platform-specific type
322 * string, a space character, then any information necessary to create
323 * the file on a supported platform. For example, if a symbolic link
324 * were being represented, the repository file would have the
325 * following contents:
327 * "link /path/to/link/target"
329 * Where 'link' is the identifier string showing that this special
330 * file should be a symbolic link and '/path/to/link/target' is the
331 * destination of the symbolic link.
333 * Special files are stored in the text-base exactly as they are
334 * stored in the repository. The platform specific files are created
335 * in the working copy at EOL/keyword translation time using
336 * svn_subst_copy_and_translate2(). If the current platform does not
337 * support a specific special file type, the file is copied into the
338 * working copy as it is seen in the repository. Because of this,
339 * users of other platforms can still view and modify the special
340 * files, even if they do not have their unique properties.
342 * New types of special files can be added by:
343 * 1. Implementing a platform-dependent routine to create a uniquely
344 * named special file and one to read the special file in
346 * 2. Creating a new textual name similar to
347 * SVN_SUBST__SPECIAL_LINK_STR in libsvn_subr/subst.c.
348 * 3. Handling the translation/detranslation case for the new type in
349 * create_special_file and detranslate_special_file, using the
355 /** A revision number. */
356 typedef long int svn_revnum_t;
358 /** Valid revision numbers begin at 0 */
359 #define SVN_IS_VALID_REVNUM(n) ((n) >= 0)
361 /** The 'official' invalid revision num */
362 #define SVN_INVALID_REVNUM ((svn_revnum_t) -1)
364 /** Not really invalid...just unimportant -- one day, this can be its
365 * own unique value, for now, just make it the same as
366 * #SVN_INVALID_REVNUM.
368 #define SVN_IGNORED_REVNUM ((svn_revnum_t) -1)
370 /** Convert NULL-terminated C string @a str to a revision number. */
371 #define SVN_STR_TO_REV(str) ((svn_revnum_t) atol(str))
374 * Parse NULL-terminated C string @a str as a revision number and
375 * store its value in @a rev. If @a endptr is non-NULL, then the
376 * address of the first non-numeric character in @a str is stored in
377 * it. If there are no digits in @a str, then @a endptr is set (if
378 * non-NULL), and the error #SVN_ERR_REVNUM_PARSE_FAILURE error is
379 * returned. Negative numbers parsed from @a str are considered
380 * invalid, and result in the same error.
385 svn_revnum_parse(svn_revnum_t *rev,
387 const char **endptr);
389 /** Originally intended to be used in printf()-style functions to format
390 * revision numbers. Deprecated due to incompatibilities with language
391 * translation tools (e.g. gettext).
393 * New code should use a bare "%ld" format specifier for formatting revision
396 * @deprecated Provided for backward compatibility with the 1.0 API.
398 #define SVN_REVNUM_T_FMT "ld"
402 /** The size of a file in the Subversion FS. */
403 typedef apr_int64_t svn_filesize_t;
405 /** The 'official' invalid file size constant. */
406 #define SVN_INVALID_FILESIZE ((svn_filesize_t) -1)
408 /** In printf()-style functions, format file sizes using this. */
409 #define SVN_FILESIZE_T_FMT APR_INT64_T_FMT
411 #ifndef DOXYGEN_SHOULD_SKIP_THIS
412 /* Parse a base-10 numeric string into a 64-bit unsigned numeric value. */
413 /* NOTE: Private. For use by Subversion's own code only. See issue #1644. */
414 /* FIXME: APR should supply a function to do this, such as "apr_atoui64". */
415 #define svn__atoui64(X) ((apr_uint64_t) apr_atoi64(X))
420 /** An enum to indicate whether recursion is needed. */
421 enum svn_recurse_kind
423 svn_nonrecursive = 1,
427 /** The concept of depth for directories.
429 * @note This is similar to, but not exactly the same as, the WebDAV
430 * and LDAP concepts of depth.
434 typedef enum svn_depth_t
436 /* The order of these depths is important: the higher the number,
437 the deeper it descends. This allows us to compare two depths
438 numerically to decide which should govern. */
440 /** Depth undetermined or ignored. In some contexts, this means the
441 client should choose an appropriate default depth. The server
442 will generally treat it as #svn_depth_infinity. */
443 svn_depth_unknown = -2,
445 /** Exclude (i.e., don't descend into) directory D.
446 @note In Subversion 1.5, svn_depth_exclude is *not* supported
447 anywhere in the client-side (libsvn_wc/libsvn_client/etc) code;
448 it is only supported as an argument to set_path functions in the
449 ra and repos reporters. (This will enable future versions of
450 Subversion to run updates, etc, against 1.5 servers with proper
451 svn_depth_exclude behavior, once we get a chance to implement
452 client-side support for svn_depth_exclude.)
454 svn_depth_exclude = -1,
456 /** Just the named directory D, no entries. Updates will not pull in
457 any files or subdirectories not already present. */
460 /** D + its file children, but not subdirs. Updates will pull in any
461 files not already present, but not subdirectories. */
464 /** D + immediate children (D and its entries). Updates will pull in
465 any files or subdirectories not already present; those
466 subdirectories' this_dir entries will have depth-empty. */
467 svn_depth_immediates = 2,
469 /** D + all descendants (full recursion from D). Updates will pull
470 in any files or subdirectories not already present; those
471 subdirectories' this_dir entries will have depth-infinity.
472 Equivalent to the pre-1.5 default update behavior. */
473 svn_depth_infinity = 3
477 /** Return a constant string expressing @a depth as an English word,
478 * e.g., "infinity", "immediates", etc. The string is not localized,
479 * as it may be used for client<->server communications.
484 svn_depth_to_word(svn_depth_t depth);
486 /** Return the appropriate depth for @a depth_str. @a word is as
487 * returned from svn_depth_to_word(). If @a depth_str does not
488 * represent a recognized depth, return #svn_depth_unknown.
493 svn_depth_from_word(const char *word);
495 /** Return #svn_depth_infinity if boolean @a recurse is TRUE, else
496 * return #svn_depth_files.
498 * @note New code should never need to use this, it is called only
499 * from pre-depth APIs, for compatibility.
503 #define SVN_DEPTH_INFINITY_OR_FILES(recurse) \
504 ((recurse) ? svn_depth_infinity : svn_depth_files)
506 /** Return #svn_depth_infinity if boolean @a recurse is TRUE, else
507 * return #svn_depth_immediates.
509 * @note New code should never need to use this, it is called only
510 * from pre-depth APIs, for compatibility.
514 #define SVN_DEPTH_INFINITY_OR_IMMEDIATES(recurse) \
515 ((recurse) ? svn_depth_infinity : svn_depth_immediates)
517 /** Return #svn_depth_infinity if boolean @a recurse is TRUE, else
518 * return #svn_depth_empty.
520 * @note New code should never need to use this, it is called only
521 * from pre-depth APIs, for compatibility.
525 #define SVN_DEPTH_INFINITY_OR_EMPTY(recurse) \
526 ((recurse) ? svn_depth_infinity : svn_depth_empty)
528 /** Return a recursion boolean based on @a depth.
530 * Although much code has been converted to use depth, some code still
531 * takes a recurse boolean. In most cases, it makes sense to treat
532 * unknown or infinite depth as recursive, and any other depth as
533 * non-recursive (which in turn usually translates to #svn_depth_files).
535 #define SVN_DEPTH_IS_RECURSIVE(depth) \
536 ((depth) == svn_depth_infinity || (depth) == svn_depth_unknown)
541 * It is sometimes convenient to indicate which parts of an #svn_dirent_t
542 * object you are actually interested in, so that calculating and sending
543 * the data corresponding to the other fields can be avoided. These values
544 * can be used for that purpose.
546 * @defgroup svn_dirent_fields Dirent fields
550 /** An indication that you are interested in the @c kind field */
551 #define SVN_DIRENT_KIND 0x00001
553 /** An indication that you are interested in the @c size field */
554 #define SVN_DIRENT_SIZE 0x00002
556 /** An indication that you are interested in the @c has_props field */
557 #define SVN_DIRENT_HAS_PROPS 0x00004
559 /** An indication that you are interested in the @c created_rev field */
560 #define SVN_DIRENT_CREATED_REV 0x00008
562 /** An indication that you are interested in the @c time field */
563 #define SVN_DIRENT_TIME 0x00010
565 /** An indication that you are interested in the @c last_author field */
566 #define SVN_DIRENT_LAST_AUTHOR 0x00020
568 /** A combination of all the dirent fields */
569 #define SVN_DIRENT_ALL ~((apr_uint32_t ) 0)
573 /** A general subversion directory entry.
575 * @note To allow for extending the #svn_dirent_t structure in future
576 * releases, always use svn_dirent_create() to allocate the stucture.
580 typedef struct svn_dirent_t
583 svn_node_kind_t kind;
585 /** length of file text, or 0 for directories */
588 /** does the node have props? */
589 svn_boolean_t has_props;
591 /** last rev in which this node changed */
592 svn_revnum_t created_rev;
594 /** time of created_rev (mod-time) */
597 /** author of created_rev */
598 const char *last_author;
600 /* IMPORTANT: If you extend this struct, check svn_dirent_dup(). */
603 /** Return a deep copy of @a dirent, allocated in @a pool.
608 svn_dirent_dup(const svn_dirent_t *dirent,
612 * Create a new svn_dirent_t instance with all values initialized to their
613 * not-available values.
618 svn_dirent_create(apr_pool_t *result_pool);
621 /** Keyword substitution.
623 * All the keywords Subversion recognizes.
625 * Note that there is a better, more general proposal out there, which
626 * would take care of both internationalization issues and custom
627 * keywords (e.g., $NetBSD$). See
630 http://subversion.tigris.org/servlets/ReadMsg?list=dev&msgNo=8921
632 From: "Jonathan M. Manning" <jmanning@alisa-jon.net>
633 To: dev@subversion.tigris.org
634 Date: Fri, 14 Dec 2001 11:56:54 -0500
635 Message-ID: <87970000.1008349014@bdldevel.bl.bdx.com>
636 Subject: Re: keywords @endverbatim
638 * and Eric Gillespie's support of same:
641 http://subversion.tigris.org/servlets/ReadMsg?list=dev&msgNo=8757
643 From: "Eric Gillespie, Jr." <epg@pretzelnet.org>
644 To: dev@subversion.tigris.org
645 Date: Wed, 12 Dec 2001 09:48:42 -0500
646 Message-ID: <87k7vsebp1.fsf@vger.pretzelnet.org>
647 Subject: Re: Customizable Keywords @endverbatim
649 * However, it is considerably more complex than the scheme below.
650 * For now we're going with simplicity, hopefully the more general
651 * solution can be done post-1.0.
653 * @defgroup svn_types_keywords Keyword definitions
657 /** The maximum size of an expanded or un-expanded keyword. */
658 #define SVN_KEYWORD_MAX_LEN 255
660 /** The most recent revision in which this file was changed. */
661 #define SVN_KEYWORD_REVISION_LONG "LastChangedRevision"
663 /** Short version of LastChangedRevision */
664 #define SVN_KEYWORD_REVISION_SHORT "Rev"
666 /** Medium version of LastChangedRevision, matching the one CVS uses.
667 * @since New in 1.1. */
668 #define SVN_KEYWORD_REVISION_MEDIUM "Revision"
670 /** The most recent date (repository time) when this file was changed. */
671 #define SVN_KEYWORD_DATE_LONG "LastChangedDate"
673 /** Short version of LastChangedDate */
674 #define SVN_KEYWORD_DATE_SHORT "Date"
676 /** Who most recently committed to this file. */
677 #define SVN_KEYWORD_AUTHOR_LONG "LastChangedBy"
679 /** Short version of LastChangedBy */
680 #define SVN_KEYWORD_AUTHOR_SHORT "Author"
682 /** The URL for the head revision of this file. */
683 #define SVN_KEYWORD_URL_LONG "HeadURL"
685 /** Short version of HeadURL */
686 #define SVN_KEYWORD_URL_SHORT "URL"
688 /** A compressed combination of the other four keywords. */
689 #define SVN_KEYWORD_ID "Id"
691 /** A full combination of the first four keywords.
692 * @since New in 1.6. */
693 #define SVN_KEYWORD_HEADER "Header"
699 /** All information about a commit.
701 * @note Objects of this type should always be created using the
702 * svn_create_commit_info() function.
706 typedef struct svn_commit_info_t
708 /** just-committed revision. */
709 svn_revnum_t revision;
711 /** server-side date of the commit. */
714 /** author of the commit. */
717 /** error message from post-commit hook, or NULL. */
718 const char *post_commit_err;
720 /** repository root, may be @c NULL if unknown.
721 @since New in 1.7. */
722 const char *repos_root;
727 * Allocate an object of type #svn_commit_info_t in @a pool and
730 * The @c revision field of the new struct is set to #SVN_INVALID_REVNUM.
731 * All other fields are initialized to @c NULL.
733 * @note Any object of the type #svn_commit_info_t should
734 * be created using this function.
735 * This is to provide for extending the svn_commit_info_t in
741 svn_create_commit_info(apr_pool_t *pool);
744 * Return a deep copy @a src_commit_info allocated in @a pool.
749 svn_commit_info_dup(const svn_commit_info_t *src_commit_info,
755 * A structure to represent a path that changed for a log entry.
757 * @note To allow for extending the #svn_log_changed_path2_t structure in
758 * future releases, always use svn_log_changed_path2_create() to allocate
763 typedef struct svn_log_changed_path2_t
765 /** 'A'dd, 'D'elete, 'R'eplace, 'M'odify */
768 /** Source path of copy (if any). */
769 const char *copyfrom_path;
771 /** Source revision of copy (if any). */
772 svn_revnum_t copyfrom_rev;
774 /** The type of the node, may be svn_node_unknown. */
775 svn_node_kind_t node_kind;
777 /** Is the text modified, may be svn_tristate_unknown.
778 * @since New in 1.7. */
779 svn_tristate_t text_modified;
781 /** Are properties modified, may be svn_tristate_unknown.
782 * @since New in 1.7. */
783 svn_tristate_t props_modified;
785 /* NOTE: Add new fields at the end to preserve binary compatibility.
786 Also, if you add fields here, you have to update
787 svn_log_changed_path2_dup(). */
788 } svn_log_changed_path2_t;
791 * Returns an #svn_log_changed_path2_t, allocated in @a pool with all fields
792 * initialized to NULL, None or empty values.
794 * @note To allow for extending the #svn_log_changed_path2_t structure in
795 * future releases, this function should always be used to allocate the
800 svn_log_changed_path2_t *
801 svn_log_changed_path2_create(apr_pool_t *pool);
804 * Return a deep copy of @a changed_path, allocated in @a pool.
808 svn_log_changed_path2_t *
809 svn_log_changed_path2_dup(const svn_log_changed_path2_t *changed_path,
813 * A structure to represent a path that changed for a log entry. Same as
814 * the first three fields of #svn_log_changed_path2_t.
816 * @deprecated Provided for backward compatibility with the 1.5 API.
818 typedef struct svn_log_changed_path_t
820 /** 'A'dd, 'D'elete, 'R'eplace, 'M'odify */
823 /** Source path of copy (if any). */
824 const char *copyfrom_path;
826 /** Source revision of copy (if any). */
827 svn_revnum_t copyfrom_rev;
829 } svn_log_changed_path_t;
832 * Return a deep copy of @a changed_path, allocated in @a pool.
835 * @deprecated Provided for backward compatibility with the 1.5 API.
838 svn_log_changed_path_t *
839 svn_log_changed_path_dup(const svn_log_changed_path_t *changed_path,
843 * A structure to represent all the information about a particular log entry.
845 * @note To allow for extending the #svn_log_entry_t structure in future
846 * releases, always use svn_log_entry_create() to allocate the structure.
850 typedef struct svn_log_entry_t
852 /** A hash containing as keys every path committed in @a revision; the
853 * values are (#svn_log_changed_path_t *) structures.
855 * The subversion core libraries will always set this field to the same
856 * value as changed_paths2 for compatibility reasons.
858 * @deprecated Provided for backward compatibility with the 1.5 API.
860 apr_hash_t *changed_paths;
862 /** The revision of the commit. */
863 svn_revnum_t revision;
865 /** The hash of requested revision properties, which may be NULL if it
866 * would contain no revprops. Maps (const char *) property name to
867 * (svn_string_t *) property value. */
868 apr_hash_t *revprops;
871 * Whether or not this message has children.
873 * When a log operation requests additional merge information, extra log
874 * entries may be returned as a result of this entry. The new entries, are
875 * considered children of the original entry, and will follow it. When
876 * the HAS_CHILDREN flag is set, the receiver should increment its stack
877 * depth, and wait until an entry is provided with SVN_INVALID_REVNUM which
878 * indicates the end of the children.
880 * For log operations which do not request additional merge information, the
881 * HAS_CHILDREN flag is always FALSE.
883 * For more information see:
884 * https://svn.apache.org/repos/asf/subversion/trunk/notes/merge-tracking/design.html#commutative-reporting
886 svn_boolean_t has_children;
888 /** A hash containing as keys every path committed in @a revision; the
889 * values are (#svn_log_changed_path2_t *) structures.
891 * If this value is not @c NULL, it MUST have the same value as
892 * changed_paths or svn_log_entry_dup() will not create an identical copy.
894 * The subversion core libraries will always set this field to the same
895 * value as changed_paths for compatibility with users assuming an older
898 * @note See http://svn.haxx.se/dev/archive-2010-08/0362.shtml for
899 * further explanation.
903 apr_hash_t *changed_paths2;
906 * Whether @a revision should be interpreted as non-inheritable in the
907 * same sense of #svn_merge_range_t.
909 * Only set when this #svn_log_entry_t instance is returned by the
910 * libsvn_client mergeinfo apis. Currently always FALSE when the
911 * #svn_log_entry_t instance is reported by the ra layer.
915 svn_boolean_t non_inheritable;
918 * Whether @a revision is a merged revision resulting from a reverse merge.
922 svn_boolean_t subtractive_merge;
924 /* NOTE: Add new fields at the end to preserve binary compatibility.
925 Also, if you add fields here, you have to update
926 svn_log_entry_dup(). */
930 * Returns an #svn_log_entry_t, allocated in @a pool with all fields
931 * initialized to NULL values.
933 * @note To allow for extending the #svn_log_entry_t structure in future
934 * releases, this function should always be used to allocate the structure.
939 svn_log_entry_create(apr_pool_t *pool);
941 /** Return a deep copy of @a log_entry, allocated in @a pool.
943 * The resulting svn_log_entry_t has @c changed_paths set to the same
944 * value as @c changed_path2. @c changed_paths will be @c NULL if
945 * @c changed_paths2 was @c NULL.
950 svn_log_entry_dup(const svn_log_entry_t *log_entry, apr_pool_t *pool);
952 /** The callback invoked by log message loopers, such as
953 * #svn_ra_plugin_t.get_log() and svn_repos_get_logs().
955 * This function is invoked once on each log message, in the order
956 * determined by the caller (see above-mentioned functions).
958 * @a baton is what you think it is, and @a log_entry contains relevant
959 * information for the log message. Any of @a log_entry->author,
960 * @a log_entry->date, or @a log_entry->message may be @c NULL.
962 * If @a log_entry->date is neither NULL nor the empty string, it was
963 * generated by svn_time_to_cstring() and can be converted to
964 * @c apr_time_t with svn_time_from_cstring().
966 * If @a log_entry->changed_paths is non-@c NULL, then it contains as keys
967 * every path committed in @a log_entry->revision; the values are
968 * (#svn_log_changed_path_t *) structures.
970 * If @a log_entry->has_children is @c TRUE, the message will be followed
971 * immediately by any number of merged revisions (child messages), which are
972 * terminated by an invocation with SVN_INVALID_REVNUM. This usage may
975 * Use @a pool for temporary allocation. If the caller is iterating
976 * over log messages, invoking this receiver on each, we recommend the
977 * standard pool loop recipe: create a subpool, pass it as @a pool to
978 * each call, clear it after each iteration, destroy it after the loop
979 * is done. (For allocation that must last beyond the lifetime of a
980 * given receiver call, use a pool in @a baton.)
984 typedef svn_error_t *(*svn_log_entry_receiver_t)(
986 svn_log_entry_t *log_entry,
990 * Similar to #svn_log_entry_receiver_t, except this uses separate
991 * parameters for each part of the log entry.
993 * @deprecated Provided for backward compatibility with the 1.4 API.
995 typedef svn_error_t *(*svn_log_message_receiver_t)(
997 apr_hash_t *changed_paths,
998 svn_revnum_t revision,
1000 const char *date, /* use svn_time_from_cstring() if need apr_time_t */
1001 const char *message,
1006 /** Callback function type for commits.
1008 * When a commit succeeds, an instance of this is invoked with the
1009 * @a commit_info, along with the @a baton closure.
1010 * @a pool can be used for temporary allocations.
1012 * @since New in 1.4.
1014 typedef svn_error_t *(*svn_commit_callback2_t)(
1015 const svn_commit_info_t *commit_info,
1019 /** Same as #svn_commit_callback2_t, but uses individual
1020 * data elements instead of the #svn_commit_info_t structure
1022 * @deprecated Provided for backward compatibility with the 1.3 API.
1024 typedef svn_error_t *(*svn_commit_callback_t)(
1025 svn_revnum_t new_revision,
1032 /** A buffer size that may be used when processing a stream of data.
1034 * @note We don't use this constant any longer, since it is considered to be
1035 * unnecessarily large.
1037 * @deprecated Provided for backwards compatibility with the 1.3 API.
1039 #define SVN_STREAM_CHUNK_SIZE 102400
1041 #ifndef DOXYGEN_SHOULD_SKIP_THIS
1043 * The maximum amount we (ideally) hold in memory at a time when
1044 * processing a stream of data.
1046 * For example, when copying data from one stream to another, do it in
1047 * blocks of this size.
1049 * NOTE: This is an internal macro, put here for convenience.
1050 * No public API may depend on the particular value of this macro.
1052 #define SVN__STREAM_CHUNK_SIZE 16384
1055 /** The maximum amount we can ever hold in memory. */
1056 /* FIXME: Should this be the same as SVN_STREAM_CHUNK_SIZE? */
1057 #define SVN_MAX_OBJECT_SIZE (((apr_size_t) -1) / 2)
1061 /* ### Note: despite being about mime-TYPES, these probably don't
1062 * ### belong in svn_types.h. However, no other header is more
1063 * ### appropriate, and didn't feel like creating svn_validate.h for
1067 /** Validate @a mime_type.
1069 * If @a mime_type does not contain a "/", or ends with non-alphanumeric
1070 * data, return #SVN_ERR_BAD_MIME_TYPE, else return success.
1072 * Use @a pool only to find error allocation.
1074 * Goal: to match both "foo/bar" and "foo/bar; charset=blah", without
1075 * being too strict about it, but to disallow mime types that have
1076 * quotes, newlines, or other garbage on the end, such as might be
1077 * unsafe in an HTTP header.
1080 svn_mime_type_validate(const char *mime_type,
1083 /** Return FALSE iff @a mime_type is a textual type.
1085 * All mime types that start with "text/" are textual, plus some special
1086 * cases (for example, "image/x-xbitmap").
1089 svn_mime_type_is_binary(const char *mime_type);
1093 /** A user defined callback that subversion will call with a user defined
1094 * baton to see if the current operation should be continued. If the operation
1095 * should continue, the function should return #SVN_NO_ERROR, if not, it
1096 * should return #SVN_ERR_CANCELLED.
1098 typedef svn_error_t *(*svn_cancel_func_t)(void *cancel_baton);
1103 * A lock object, for client & server to share.
1105 * A lock represents the exclusive right to add, delete, or modify a
1106 * path. A lock is created in a repository, wholly controlled by the
1107 * repository. A "lock-token" is the lock's UUID, and can be used to
1108 * learn more about a lock's fields, and or/make use of the lock.
1109 * Because a lock is immutable, a client is free to not only cache the
1110 * lock-token, but the lock's fields too, for convenience.
1112 * Note that the 'is_dav_comment' field is wholly ignored by every
1113 * library except for mod_dav_svn. The field isn't even marshalled
1114 * over the network to the client. Assuming lock structures are
1115 * created with apr_pcalloc(), a default value of 0 is universally safe.
1117 * @note in the current implementation, only files are lockable.
1119 * @since New in 1.2.
1121 typedef struct svn_lock_t
1123 const char *path; /**< the path this lock applies to */
1124 const char *token; /**< unique URI representing lock */
1125 const char *owner; /**< the username which owns the lock */
1126 const char *comment; /**< (optional) description of lock */
1127 svn_boolean_t is_dav_comment; /**< was comment made by generic DAV client? */
1128 apr_time_t creation_date; /**< when lock was made */
1129 apr_time_t expiration_date; /**< (optional) when lock will expire;
1130 If value is 0, lock will never expire. */
1134 * Returns an #svn_lock_t, allocated in @a pool with all fields initialized
1137 * @note To allow for extending the #svn_lock_t structure in the future
1138 * releases, this function should always be used to allocate the structure.
1140 * @since New in 1.2.
1143 svn_lock_create(apr_pool_t *pool);
1146 * Return a deep copy of @a lock, allocated in @a pool.
1148 * @since New in 1.2.
1151 svn_lock_dup(const svn_lock_t *lock, apr_pool_t *pool);
1156 * Return a formatted Universal Unique IDentifier (UUID) string.
1158 * @since New in 1.4.
1161 svn_uuid_generate(apr_pool_t *pool);
1166 * Mergeinfo representing a merge of a range of revisions.
1170 typedef struct svn_merge_range_t
1173 * If the 'start' field is less than the 'end' field then 'start' is
1174 * exclusive and 'end' inclusive of the range described. This is termed
1175 * a forward merge range. If 'start' is greater than 'end' then the
1176 * opposite is true. This is termed a reverse merge range. If 'start'
1177 * equals 'end' the meaning of the range is not defined.
1183 * Whether this merge range should be inherited by treewise
1184 * descendants of the path to which the range applies. */
1185 svn_boolean_t inheritable;
1186 } svn_merge_range_t;
1189 * Return a copy of @a range, allocated in @a pool.
1191 * @since New in 1.5.
1194 svn_merge_range_dup(const svn_merge_range_t *range, apr_pool_t *pool);
1197 * Returns true if the changeset committed in revision @a rev is one
1198 * of the changesets in the range @a range.
1200 * @since New in 1.5.
1203 svn_merge_range_contains_rev(const svn_merge_range_t *range, svn_revnum_t rev);
1207 /** @defgroup node_location_seg_reporting Node location segment reporting.
1211 * A representation of a segment of an object's version history with an
1212 * emphasis on the object's location in the repository as of various
1215 * @since New in 1.5.
1217 typedef struct svn_location_segment_t
1219 /** The beginning (oldest) and ending (youngest) revisions for this
1220 segment, both inclusive. */
1221 svn_revnum_t range_start;
1222 svn_revnum_t range_end;
1224 /** The absolute (sans leading slash) path for this segment. May be
1225 NULL to indicate gaps in an object's history. */
1228 } svn_location_segment_t;
1231 * A callback invoked by generators of #svn_location_segment_t
1232 * objects, used to report information about a versioned object's
1233 * history in terms of its location in the repository filesystem over
1236 typedef svn_error_t *(*svn_location_segment_receiver_t)(
1237 svn_location_segment_t *segment,
1242 * Return a deep copy of @a segment, allocated in @a pool.
1244 * @since New in 1.5.
1246 svn_location_segment_t *
1247 svn_location_segment_dup(const svn_location_segment_t *segment,
1254 /** A line number, such as in a file or a stream.
1256 * @since New in 1.7.
1258 typedef unsigned long svn_linenum_t;
1260 /** The maximum value of an svn_linenum_t.
1262 * @since New in 1.7.
1264 #define SVN_LINENUM_MAX_VALUE ULONG_MAX
1270 #endif /* __cplusplus */
1274 * Everybody and their brother needs to deal with svn_error_t, the error
1275 * codes, and whatever else. While they *should* go and include svn_error.h
1276 * in order to do that... bah. Let's just help everybody out and include
1277 * that header whenever somebody grabs svn_types.h.
1279 * Note that we do this at the END of this header so that its contents
1280 * are available to svn_error.h (our guards will prevent the circular
1281 * include). We also need to do the include *outside* of the cplusplus
1284 #include "svn_error.h"
1288 * Subversion developers may want to use some additional debugging facilities
1289 * while working on the code. We'll pull that in here, so individual source
1290 * files don't have to include this header manually.
1293 #include "private/svn_debug.h"
1297 #endif /* SVN_TYPES_H */