svn_types.h revision 369302
1/** 2 * @copyright 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 11 * 12 * http://www.apache.org/licenses/LICENSE-2.0 13 * 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 19 * under the License. 20 * ==================================================================== 21 * @endcopyright 22 * 23 * @file svn_types.h 24 * @brief Subversion's data types 25 */ 26 27#ifndef SVN_TYPES_H 28#define SVN_TYPES_H 29 30#include "svn_types_impl.h" 31 32/* ### this should go away, but it causes too much breakage right now */ 33#include <stdlib.h> 34#include <limits.h> /* for ULONG_MAX */ 35 36#include <apr.h> /* for apr_size_t, apr_int64_t, ... */ 37#include <apr_version.h> 38#include <apr_errno.h> /* for apr_status_t */ 39#include <apr_pools.h> /* for apr_pool_t */ 40#include <apr_hash.h> /* for apr_hash_t */ 41#include <apr_tables.h> /* for apr_array_push() */ 42#include <apr_time.h> /* for apr_time_t */ 43#include <apr_strings.h> /* for apr_atoi64() */ 44 45#ifdef __cplusplus 46extern "C" { 47#endif /* __cplusplus */ 48 49 50 51/** Macro used to mark deprecated functions. 52 * 53 * @since New in 1.6. 54 */ 55#ifndef SVN_DEPRECATED 56# if !defined(SWIGPERL) && !defined(SWIGPYTHON) && !defined(SWIGRUBY) 57# if defined(__GNUC__) && (__GNUC__ >= 4 || (__GNUC__==3 && __GNUC_MINOR__>=1)) 58# define SVN_DEPRECATED __attribute__((deprecated)) 59# elif defined(_MSC_VER) && _MSC_VER >= 1300 60# define SVN_DEPRECATED __declspec(deprecated) 61# else 62# define SVN_DEPRECATED 63# endif 64# else 65# define SVN_DEPRECATED 66# endif 67#endif 68 69 70/** Macro used to mark experimental functions. 71 * 72 * @since New in 1.9. 73 */ 74#ifndef SVN_EXPERIMENTAL 75# if !defined(SWIGPERL) && !defined(SWIGPYTHON) && !defined(SWIGRUBY) 76# if defined(__has_attribute) 77# if __has_attribute(__warning__) 78# define SVN_EXPERIMENTAL __attribute__((warning("experimental function used"))) 79# else 80# define SVN_EXPERIMENTAL 81# endif 82# elif !defined(__llvm__) && defined(__GNUC__) \ 83 && (__GNUC__ >= 4 || (__GNUC__==3 && __GNUC_MINOR__>=1)) 84# define SVN_EXPERIMENTAL __attribute__((warning("experimental function used"))) 85# elif defined(_MSC_VER) && _MSC_VER >= 1300 86# define SVN_EXPERIMENTAL __declspec(deprecated("experimental function used")) 87# else 88# define SVN_EXPERIMENTAL 89# endif 90# else 91# define SVN_EXPERIMENTAL 92# endif 93#endif 94 95/** Macro used to mark functions that require a final null sentinel argument. 96 * 97 * @since New in 1.9. 98 */ 99#ifndef SVN_NEEDS_SENTINEL_NULL 100# if defined(__has_attribute) 101# if __has_attribute(__sentinel__) 102# define SVN_NEEDS_SENTINEL_NULL __attribute__((sentinel)) 103# else 104# define SVN_NEEDS_SENTINEL_NULL 105# endif 106# elif defined(__GNUC__) && (__GNUC__ >= 4) 107# define SVN_NEEDS_SENTINEL_NULL __attribute__((sentinel)) 108# else 109# define SVN_NEEDS_SENTINEL_NULL 110# endif 111#endif 112 113 114/** Indicate whether the current platform supports unaligned data access. 115 * 116 * On the majority of machines running SVN (x86 / x64), unaligned access 117 * is much cheaper than repeated aligned access. Define this macro to 1 118 * on those machines. 119 * Unaligned access on other machines (e.g. IA64) will trigger memory 120 * access faults or simply misbehave. 121 * 122 * Note: Some platforms may only support unaligned access for integers 123 * (PowerPC). As a result this macro should only be used to determine 124 * if unaligned access is supported for integers. 125 * 126 * @since New in 1.7. 127 */ 128#ifndef SVN_UNALIGNED_ACCESS_IS_OK 129# if defined(_M_IX86) || defined(i386) \ 130 || defined(_M_X64) || defined(__x86_64) \ 131 || defined(__powerpc__) || defined(__ppc__) 132# define SVN_UNALIGNED_ACCESS_IS_OK 1 133# else 134# define SVN_UNALIGNED_ACCESS_IS_OK 0 135# endif 136#endif 137 138 139 140/** YABT: Yet Another Boolean Type */ 141typedef int svn_boolean_t; 142 143#ifndef TRUE 144/** uhh... true */ 145#define TRUE 1 146#endif /* TRUE */ 147 148#ifndef FALSE 149/** uhh... false */ 150#define FALSE 0 151#endif /* FALSE */ 152 153 154 155/* Declaration of a unique type, never defined, for the SVN_VA_NULL macro. 156 * 157 * NOTE: Private. Not for direct use by third-party code. 158 */ 159struct svn__null_pointer_constant_stdarg_sentinel_t; 160 161/** Null pointer constant used as a sentinel in variable argument lists. 162 * 163 * Use of this macro ensures that the argument is of the correct size when a 164 * pointer is expected. (The macro @c NULL is not defined as a pointer on 165 * all systems, and the arguments to variadic functions are not converted 166 * automatically to the expected type.) 167 * 168 * @since New in 1.9. 169 */ 170#define SVN_VA_NULL ((struct svn__null_pointer_constant_stdarg_sentinel_t*)0) 171/* See? (char*)NULL -- They have the same length, but the cast looks ugly. */ 172 173 174 175/** Subversion error object. 176 * 177 * Defined here, rather than in svn_error.h, to avoid a recursive @#include 178 * situation. 179 */ 180typedef struct svn_error_t 181{ 182 /** APR error value; possibly an SVN_ custom error code (see 183 * `svn_error_codes.h' for a full listing). 184 */ 185 apr_status_t apr_err; 186 187 /** Details from the producer of error. 188 * 189 * Note that if this error was generated by Subversion's API, you'll 190 * probably want to use svn_err_best_message() to get a single 191 * descriptive string for this error chain (see the @a child member) 192 * or svn_handle_error2() to print the error chain in full. This is 193 * because Subversion's API functions sometimes add many links to 194 * the error chain that lack details (used only to produce virtual 195 * stack traces). (Use svn_error_purge_tracing() to remove those 196 * trace-only links from the error chain.) 197 */ 198 const char *message; 199 200 /** Pointer to the error we "wrap" (may be @c NULL). Via this 201 * member, individual error object can be strung together into an 202 * "error chain". 203 */ 204 struct svn_error_t *child; 205 206 /** The pool in which this error object is allocated. (If 207 * Subversion's APIs are used to manage error chains, then this pool 208 * will contain the whole error chain of which this object is a 209 * member.) */ 210 apr_pool_t *pool; 211 212 /** Source file where the error originated (iff @c SVN_DEBUG; 213 * undefined otherwise). 214 */ 215 const char *file; 216 217 /** Source line where the error originated (iff @c SVN_DEBUG; 218 * undefined otherwise). 219 */ 220 long line; 221 222} svn_error_t; 223 224 225 226/* See svn_version.h. 227 Defined here to avoid including svn_version.h from all public headers. */ 228typedef struct svn_version_t svn_version_t; 229 230 231 232/** @defgroup APR_ARRAY_compat_macros APR Array Compatibility Helper Macros 233 * These macros are provided by APR itself from version 1.3. 234 * Definitions are provided here for when using older versions of APR. 235 * @{ 236 */ 237 238/** index into an apr_array_header_t */ 239#ifndef APR_ARRAY_IDX 240#define APR_ARRAY_IDX(ary,i,type) (((type *)(ary)->elts)[i]) 241#endif 242 243/** easier array-pushing syntax */ 244#ifndef APR_ARRAY_PUSH 245#define APR_ARRAY_PUSH(ary,type) (*((type *)apr_array_push(ary))) 246#endif 247 248/** @} */ 249 250 251 252/** @defgroup apr_hash_utilities APR Hash Table Helpers 253 * These functions enable the caller to dereference an APR hash table index 254 * without type casts or temporary variables. 255 * 256 * These functions are provided by APR itself from version 1.5. 257 * Definitions are provided here for when using older versions of APR. 258 * @{ 259 */ 260 261#if !APR_VERSION_AT_LEAST(1, 5, 0) 262 263/** Return the key of the hash table entry indexed by @a hi. */ 264const void * 265apr_hash_this_key(apr_hash_index_t *hi); 266 267/** Return the key length of the hash table entry indexed by @a hi. */ 268apr_ssize_t 269apr_hash_this_key_len(apr_hash_index_t *hi); 270 271/** Return the value of the hash table entry indexed by @a hi. */ 272void * 273apr_hash_this_val(apr_hash_index_t *hi); 274 275#endif 276 277/** @} */ 278 279 280 281/** On Windows, APR_STATUS_IS_ENOTDIR includes several kinds of 282 * invalid-pathname error but not ERROR_INVALID_NAME, so we include it. 283 * We also include ERROR_DIRECTORY as that was not included in apr versions 284 * before 1.4.0 and this fix is not backported */ 285/* ### These fixes should go into APR. */ 286#ifndef WIN32 287#define SVN__APR_STATUS_IS_ENOTDIR(s) APR_STATUS_IS_ENOTDIR(s) 288#else 289#define SVN__APR_STATUS_IS_ENOTDIR(s) (APR_STATUS_IS_ENOTDIR(s) \ 290 || ((s) == APR_OS_START_SYSERR + ERROR_DIRECTORY) \ 291 || ((s) == APR_OS_START_SYSERR + ERROR_INVALID_NAME)) 292#endif 293 294/** On Windows, APR_STATUS_IS_EPIPE does not include ERROR_NO_DATA error. 295 * So we include it.*/ 296/* ### These fixes should go into APR. */ 297#ifndef WIN32 298#define SVN__APR_STATUS_IS_EPIPE(s) APR_STATUS_IS_EPIPE(s) 299#else 300#define SVN__APR_STATUS_IS_EPIPE(s) (APR_STATUS_IS_EPIPE(s) \ 301 || ((s) == APR_OS_START_SYSERR + ERROR_NO_DATA)) 302#endif 303 304/** @} */ 305 306 307 308/* NOTE: svn_node_kind_t is defined in svn_types_impl.h */ 309 310/** Return a constant string expressing @a kind as an English word, e.g., 311 * "file", "dir", etc. The string is not localized, as it may be used for 312 * client<->server communications. If the kind is not recognized, return 313 * "unknown". 314 * 315 * @since New in 1.6. 316 */ 317const char * 318svn_node_kind_to_word(svn_node_kind_t kind); 319 320/** Return the appropriate node_kind for @a word. @a word is as 321 * returned from svn_node_kind_to_word(). If @a word does not 322 * represent a recognized kind or is @c NULL, return #svn_node_unknown. 323 * 324 * @since New in 1.6. 325 */ 326svn_node_kind_t 327svn_node_kind_from_word(const char *word); 328 329 330/* NOTE: svn_tristate_t is defined in svn_types_impl.h */ 331 332/** Return a constant string "true", "false" or NULL representing the value of 333 * @a tristate. 334 * 335 * @since New in 1.7. 336 */ 337const char * 338svn_tristate__to_word(svn_tristate_t tristate); 339 340/** Return the appropriate tristate for @a word. If @a word is "true", returns 341 * #svn_tristate_true; if @a word is "false", returns #svn_tristate_false, 342 * for all other values (including NULL) returns #svn_tristate_unknown. 343 * 344 * @since New in 1.7. 345 */ 346svn_tristate_t 347svn_tristate__from_word(const char * word); 348 349 350 351/** About Special Files in Subversion 352 * 353 * Subversion denotes files that cannot be portably created or 354 * modified as "special" files (svn_node_special). It stores these 355 * files in the repository as a plain text file with the svn:special 356 * property set. The file contents contain: a platform-specific type 357 * string, a space character, then any information necessary to create 358 * the file on a supported platform. For example, if a symbolic link 359 * were being represented, the repository file would have the 360 * following contents: 361 * 362 * "link /path/to/link/target" 363 * 364 * Where 'link' is the identifier string showing that this special 365 * file should be a symbolic link and '/path/to/link/target' is the 366 * destination of the symbolic link. 367 * 368 * Special files are stored in the text-base exactly as they are 369 * stored in the repository. The platform specific files are created 370 * in the working copy at EOL/keyword translation time using 371 * svn_subst_copy_and_translate2(). If the current platform does not 372 * support a specific special file type, the file is copied into the 373 * working copy as it is seen in the repository. Because of this, 374 * users of other platforms can still view and modify the special 375 * files, even if they do not have their unique properties. 376 * 377 * New types of special files can be added by: 378 * 1. Implementing a platform-dependent routine to create a uniquely 379 * named special file and one to read the special file in 380 * libsvn_subr/io.c. 381 * 2. Creating a new textual name similar to 382 * SVN_SUBST__SPECIAL_LINK_STR in libsvn_subr/subst.c. 383 * 3. Handling the translation/detranslation case for the new type in 384 * create_special_file_from_stream and detranslate_special_file, using the 385 * routines from 1. 386 */ 387 388 389 390/* NOTE: svn_revnum_t and SVN_INVALID_REVNUM are defined in svn_types_impl.h */ 391 392/** Valid revision numbers begin at 0 */ 393#define SVN_IS_VALID_REVNUM(n) ((n) >= 0) 394 395/** Not really invalid...just unimportant -- one day, this can be its 396 * own unique value, for now, just make it the same as 397 * #SVN_INVALID_REVNUM. 398 */ 399#define SVN_IGNORED_REVNUM ((svn_revnum_t) -1) 400 401/** Convert NULL-terminated C string @a str to a revision number. */ 402#define SVN_STR_TO_REV(str) ((svn_revnum_t) atol(str)) 403 404/** 405 * Parse NULL-terminated C string @a str as a revision number and 406 * store its value in @a rev. If @a endptr is non-NULL, then the 407 * address of the first non-numeric character in @a str is stored in 408 * it. If there are no digits in @a str, then @a endptr is set (if 409 * non-NULL), and the error #SVN_ERR_REVNUM_PARSE_FAILURE error is 410 * returned. Negative numbers parsed from @a str are considered 411 * invalid, and result in the same error. 412 * 413 * @since New in 1.5. 414 */ 415svn_error_t * 416svn_revnum_parse(svn_revnum_t *rev, 417 const char *str, 418 const char **endptr); 419 420/** Originally intended to be used in printf()-style functions to format 421 * revision numbers. Deprecated due to incompatibilities with language 422 * translation tools (e.g. gettext). 423 * 424 * New code should use a bare "%ld" format specifier for formatting revision 425 * numbers. 426 * 427 * @deprecated Provided for backward compatibility with the 1.0 API. 428 */ 429#define SVN_REVNUM_T_FMT "ld" 430 431 432 433/** The size of a file in the Subversion FS. */ 434typedef apr_int64_t svn_filesize_t; 435 436/** The 'official' invalid file size constant. */ 437#define SVN_INVALID_FILESIZE ((svn_filesize_t) -1) 438 439/** In printf()-style functions, format file sizes using this. */ 440#define SVN_FILESIZE_T_FMT APR_INT64_T_FMT 441 442#ifndef DOXYGEN_SHOULD_SKIP_THIS 443/* Parse a base-10 numeric string into a 64-bit unsigned numeric value. */ 444/* NOTE: Private. For use by Subversion's own code only. See issue #1644. */ 445/* FIXME: APR should supply a function to do this, such as "apr_atoui64". */ 446#define svn__atoui64(X) ((apr_uint64_t) apr_atoi64(X)) 447#endif 448 449 450 451/** An enum to indicate whether recursion is needed. */ 452enum svn_recurse_kind 453{ 454 svn_nonrecursive = 1, 455 svn_recursive 456}; 457 458/* NOTE: svn_depth_t is defined in svn_types_impl.h */ 459 460/** Return a constant string expressing @a depth as an English word, 461 * e.g., "infinity", "immediates", etc. The string is not localized, 462 * as it may be used for client<->server communications. 463 * 464 * @since New in 1.5. 465 */ 466const char * 467svn_depth_to_word(svn_depth_t depth); 468 469/** Return the appropriate depth for @a depth_str. @a word is as 470 * returned from svn_depth_to_word(). If @a depth_str does not 471 * represent a recognized depth, return #svn_depth_unknown. 472 * 473 * @since New in 1.5. 474 */ 475svn_depth_t 476svn_depth_from_word(const char *word); 477 478/** Return #svn_depth_infinity if boolean @a recurse is TRUE, else 479 * return #svn_depth_files. 480 * 481 * @note New code should never need to use this, it is called only 482 * from pre-depth APIs, for compatibility. 483 * 484 * @since New in 1.5. 485 */ 486#define SVN_DEPTH_INFINITY_OR_FILES(recurse) \ 487 ((recurse) ? svn_depth_infinity : svn_depth_files) 488 489/** Return #svn_depth_infinity if boolean @a recurse is TRUE, else 490 * return #svn_depth_immediates. 491 * 492 * @note New code should never need to use this, it is called only 493 * from pre-depth APIs, for compatibility. 494 * 495 * @since New in 1.5. 496 */ 497#define SVN_DEPTH_INFINITY_OR_IMMEDIATES(recurse) \ 498 ((recurse) ? svn_depth_infinity : svn_depth_immediates) 499 500/** Return #svn_depth_infinity if boolean @a recurse is TRUE, else 501 * return #svn_depth_empty. 502 * 503 * @note New code should never need to use this, it is called only 504 * from pre-depth APIs, for compatibility. 505 * 506 * @since New in 1.5. 507 */ 508#define SVN_DEPTH_INFINITY_OR_EMPTY(recurse) \ 509 ((recurse) ? svn_depth_infinity : svn_depth_empty) 510 511/** Return a recursion boolean based on @a depth. 512 * 513 * Although much code has been converted to use depth, some code still 514 * takes a recurse boolean. In most cases, it makes sense to treat 515 * unknown or infinite depth as recursive, and any other depth as 516 * non-recursive (which in turn usually translates to #svn_depth_files). 517 */ 518#define SVN_DEPTH_IS_RECURSIVE(depth) \ 519 ((depth) == svn_depth_infinity || (depth) == svn_depth_unknown) 520 521 522 523/** 524 * It is sometimes convenient to indicate which parts of an #svn_dirent_t 525 * object you are actually interested in, so that calculating and sending 526 * the data corresponding to the other fields can be avoided. These values 527 * can be used for that purpose. 528 * 529 * @defgroup svn_dirent_fields Dirent fields 530 * @{ 531 */ 532 533/** An indication that you are interested in the @c kind field */ 534#define SVN_DIRENT_KIND 0x00001 535 536/** An indication that you are interested in the @c size field */ 537#define SVN_DIRENT_SIZE 0x00002 538 539/** An indication that you are interested in the @c has_props field */ 540#define SVN_DIRENT_HAS_PROPS 0x00004 541 542/** An indication that you are interested in the @c created_rev field */ 543#define SVN_DIRENT_CREATED_REV 0x00008 544 545/** An indication that you are interested in the @c time field */ 546#define SVN_DIRENT_TIME 0x00010 547 548/** An indication that you are interested in the @c last_author field */ 549#define SVN_DIRENT_LAST_AUTHOR 0x00020 550 551/** A combination of all the dirent fields */ 552#define SVN_DIRENT_ALL ~((apr_uint32_t ) 0) 553 554/** @} */ 555 556/** A general subversion directory entry. 557 * 558 * @note To allow for extending the #svn_dirent_t structure in future 559 * releases, always use svn_dirent_create() to allocate the stucture. 560 * 561 * @since New in 1.6. 562 */ 563typedef struct svn_dirent_t 564{ 565 /** node kind */ 566 svn_node_kind_t kind; 567 568 /** length of file text, otherwise SVN_INVALID_FILESIZE */ 569 svn_filesize_t size; 570 571 /** does the node have props? */ 572 svn_boolean_t has_props; 573 574 /** last rev in which this node changed */ 575 svn_revnum_t created_rev; 576 577 /** time of created_rev (mod-time) */ 578 apr_time_t time; 579 580 /** author of created_rev */ 581 const char *last_author; 582 583 /* IMPORTANT: If you extend this struct, check svn_dirent_dup(). */ 584} svn_dirent_t; 585 586/** Return a deep copy of @a dirent, allocated in @a pool. 587 * 588 * @since New in 1.4. 589 */ 590svn_dirent_t * 591svn_dirent_dup(const svn_dirent_t *dirent, 592 apr_pool_t *pool); 593 594/** 595 * Create a new svn_dirent_t instance with all values initialized to their 596 * not-available values. 597 * 598 * @since New in 1.8. 599 */ 600svn_dirent_t * 601svn_dirent_create(apr_pool_t *result_pool); 602 603 604/** Keyword substitution. 605 * 606 * All the keywords Subversion recognizes. 607 * 608 * Note that there is a better, more general proposal out there, which 609 * would take care of both internationalization issues and custom 610 * keywords (e.g., $NetBSD$). See 611 * 612 * @verbatim 613 http://subversion.tigris.org/servlets/ReadMsg?list=dev&msgNo=8921 614 ===== 615 From: "Jonathan M. Manning" <jmanning@alisa-jon.net> 616 To: dev@subversion.tigris.org 617 Date: Fri, 14 Dec 2001 11:56:54 -0500 618 Message-ID: <87970000.1008349014@bdldevel.bl.bdx.com> 619 Subject: Re: keywords @endverbatim 620 * 621 * and Eric Gillespie's support of same: 622 * 623 * @verbatim 624 http://subversion.tigris.org/servlets/ReadMsg?list=dev&msgNo=8757 625 ===== 626 From: "Eric Gillespie, Jr." <epg@pretzelnet.org> 627 To: dev@subversion.tigris.org 628 Date: Wed, 12 Dec 2001 09:48:42 -0500 629 Message-ID: <87k7vsebp1.fsf@vger.pretzelnet.org> 630 Subject: Re: Customizable Keywords @endverbatim 631 * 632 * However, it is considerably more complex than the scheme below. 633 * For now we're going with simplicity, hopefully the more general 634 * solution can be done post-1.0. 635 * 636 * @defgroup svn_types_keywords Keyword definitions 637 * @{ 638 */ 639 640/** The maximum size of an expanded or un-expanded keyword. */ 641#define SVN_KEYWORD_MAX_LEN 255 642 643/** The most recent revision in which this file was changed. */ 644#define SVN_KEYWORD_REVISION_LONG "LastChangedRevision" 645 646/** Short version of LastChangedRevision */ 647#define SVN_KEYWORD_REVISION_SHORT "Rev" 648 649/** Medium version of LastChangedRevision, matching the one CVS uses. 650 * @since New in 1.1. */ 651#define SVN_KEYWORD_REVISION_MEDIUM "Revision" 652 653/** The most recent date (repository time) when this file was changed. */ 654#define SVN_KEYWORD_DATE_LONG "LastChangedDate" 655 656/** Short version of LastChangedDate */ 657#define SVN_KEYWORD_DATE_SHORT "Date" 658 659/** Who most recently committed to this file. */ 660#define SVN_KEYWORD_AUTHOR_LONG "LastChangedBy" 661 662/** Short version of LastChangedBy */ 663#define SVN_KEYWORD_AUTHOR_SHORT "Author" 664 665/** The URL for the head revision of this file. */ 666#define SVN_KEYWORD_URL_LONG "HeadURL" 667 668/** Short version of HeadURL */ 669#define SVN_KEYWORD_URL_SHORT "URL" 670 671/** A compressed combination of the other four keywords. */ 672#define SVN_KEYWORD_ID "Id" 673 674/** A full combination of the first four keywords. 675 * @since New in 1.6. */ 676#define SVN_KEYWORD_HEADER "Header" 677 678/** @} */ 679 680 681 682/** All information about a commit. 683 * 684 * @note Objects of this type should always be created using the 685 * svn_create_commit_info() function. 686 * 687 * @since New in 1.3. 688 */ 689typedef struct svn_commit_info_t 690{ 691 /** just-committed revision. */ 692 svn_revnum_t revision; 693 694 /** server-side date of the commit. */ 695 const char *date; 696 697 /** author of the commit. */ 698 const char *author; 699 700 /** error message from post-commit hook, or NULL. */ 701 const char *post_commit_err; 702 703 /** repository root, may be @c NULL if unknown. 704 @since New in 1.7. */ 705 const char *repos_root; 706 707} svn_commit_info_t; 708 709/** 710 * Allocate an object of type #svn_commit_info_t in @a pool and 711 * return it. 712 * 713 * The @c revision field of the new struct is set to #SVN_INVALID_REVNUM. 714 * All other fields are initialized to @c NULL. 715 * 716 * @note Any object of the type #svn_commit_info_t should 717 * be created using this function. 718 * This is to provide for extending the svn_commit_info_t in 719 * the future. 720 * 721 * @since New in 1.3. 722 */ 723svn_commit_info_t * 724svn_create_commit_info(apr_pool_t *pool); 725 726/** 727 * Return a deep copy @a src_commit_info allocated in @a pool. 728 * 729 * @since New in 1.4. 730 */ 731svn_commit_info_t * 732svn_commit_info_dup(const svn_commit_info_t *src_commit_info, 733 apr_pool_t *pool); 734 735 736 737/** 738 * A structure to represent a path that changed for a log entry. 739 * 740 * @note To allow for extending the #svn_log_changed_path2_t structure in 741 * future releases, always use svn_log_changed_path2_create() to allocate 742 * the structure. 743 * 744 * @since New in 1.6. 745 */ 746typedef struct svn_log_changed_path2_t 747{ 748 /** 'A'dd, 'D'elete, 'R'eplace, 'M'odify */ 749 char action; 750 751 /** Source path of copy (if any). */ 752 const char *copyfrom_path; 753 754 /** Source revision of copy (if any). */ 755 svn_revnum_t copyfrom_rev; 756 757 /** The type of the node, may be svn_node_unknown. */ 758 svn_node_kind_t node_kind; 759 760 /** Is the text modified, may be svn_tristate_unknown. 761 * @since New in 1.7. */ 762 svn_tristate_t text_modified; 763 764 /** Are properties modified, may be svn_tristate_unknown. 765 * @since New in 1.7. */ 766 svn_tristate_t props_modified; 767 768 /* NOTE: Add new fields at the end to preserve binary compatibility. 769 Also, if you add fields here, you have to update 770 svn_log_changed_path2_dup(). */ 771} svn_log_changed_path2_t; 772 773/** 774 * Returns an #svn_log_changed_path2_t, allocated in @a pool with all fields 775 * initialized to NULL, None or empty values. 776 * 777 * @note To allow for extending the #svn_log_changed_path2_t structure in 778 * future releases, this function should always be used to allocate the 779 * structure. 780 * 781 * @since New in 1.6. 782 */ 783svn_log_changed_path2_t * 784svn_log_changed_path2_create(apr_pool_t *pool); 785 786/** 787 * Return a deep copy of @a changed_path, allocated in @a pool. 788 * 789 * @since New in 1.6. 790 */ 791svn_log_changed_path2_t * 792svn_log_changed_path2_dup(const svn_log_changed_path2_t *changed_path, 793 apr_pool_t *pool); 794 795/** 796 * A structure to represent a path that changed for a log entry. Same as 797 * the first three fields of #svn_log_changed_path2_t. 798 * 799 * @deprecated Provided for backward compatibility with the 1.5 API. 800 */ 801typedef struct svn_log_changed_path_t 802{ 803 /** 'A'dd, 'D'elete, 'R'eplace, 'M'odify */ 804 char action; 805 806 /** Source path of copy (if any). */ 807 const char *copyfrom_path; 808 809 /** Source revision of copy (if any). */ 810 svn_revnum_t copyfrom_rev; 811 812} svn_log_changed_path_t; 813 814/** 815 * Return a deep copy of @a changed_path, allocated in @a pool. 816 * 817 * @since New in 1.3. 818 * @deprecated Provided for backward compatibility with the 1.5 API. 819 */ 820SVN_DEPRECATED 821svn_log_changed_path_t * 822svn_log_changed_path_dup(const svn_log_changed_path_t *changed_path, 823 apr_pool_t *pool); 824 825/** 826 * A structure to represent all the information about a particular log entry. 827 * 828 * @note To allow for extending the #svn_log_entry_t structure in future 829 * releases, always use svn_log_entry_create() to allocate the structure. 830 * 831 * @since New in 1.5. 832 */ 833typedef struct svn_log_entry_t 834{ 835 /** A hash containing as keys every path committed in @a revision; the 836 * values are (#svn_log_changed_path_t *) structures. 837 * 838 * The subversion core libraries will always set this field to the same 839 * value as changed_paths2 for compatibility reasons. 840 * 841 * @deprecated Provided for backward compatibility with the 1.5 API. 842 */ 843 apr_hash_t *changed_paths; 844 845 /** The revision of the commit. */ 846 svn_revnum_t revision; 847 848 /** The hash of requested revision properties, which may be NULL if it 849 * would contain no revprops. Maps (const char *) property name to 850 * (svn_string_t *) property value. */ 851 apr_hash_t *revprops; 852 853 /** 854 * Whether or not this message has children. 855 * 856 * When a log operation requests additional merge information, extra log 857 * entries may be returned as a result of this entry. The new entries, are 858 * considered children of the original entry, and will follow it. When 859 * the HAS_CHILDREN flag is set, the receiver should increment its stack 860 * depth, and wait until an entry is provided with SVN_INVALID_REVNUM which 861 * indicates the end of the children. 862 * 863 * For log operations which do not request additional merge information, the 864 * HAS_CHILDREN flag is always FALSE. 865 * 866 * For more information see: 867 * https://svn.apache.org/repos/asf/subversion/trunk/notes/merge-tracking/design.html#commutative-reporting 868 */ 869 svn_boolean_t has_children; 870 871 /** A hash containing as keys every path committed in @a revision; the 872 * values are (#svn_log_changed_path2_t *) structures. 873 * 874 * If this value is not @c NULL, it MUST have the same value as 875 * changed_paths or svn_log_entry_dup() will not create an identical copy. 876 * 877 * The subversion core libraries will always set this field to the same 878 * value as changed_paths for compatibility with users assuming an older 879 * version. 880 * 881 * @note See http://svn.haxx.se/dev/archive-2010-08/0362.shtml for 882 * further explanation. 883 * 884 * @since New in 1.6. 885 */ 886 apr_hash_t *changed_paths2; 887 888 /** 889 * Whether @a revision should be interpreted as non-inheritable in the 890 * same sense of #svn_merge_range_t. 891 * 892 * Only set when this #svn_log_entry_t instance is returned by the 893 * libsvn_client mergeinfo apis. Currently always FALSE when the 894 * #svn_log_entry_t instance is reported by the ra layer. 895 * 896 * @since New in 1.7. 897 */ 898 svn_boolean_t non_inheritable; 899 900 /** 901 * Whether @a revision is a merged revision resulting from a reverse merge. 902 * 903 * @since New in 1.7. 904 */ 905 svn_boolean_t subtractive_merge; 906 907 /* NOTE: Add new fields at the end to preserve binary compatibility. 908 Also, if you add fields here, you have to update 909 svn_log_entry_dup(). */ 910} svn_log_entry_t; 911 912/** 913 * Returns an #svn_log_entry_t, allocated in @a pool with all fields 914 * initialized to NULL values. 915 * 916 * @note To allow for extending the #svn_log_entry_t structure in future 917 * releases, this function should always be used to allocate the structure. 918 * 919 * @since New in 1.5. 920 */ 921svn_log_entry_t * 922svn_log_entry_create(apr_pool_t *pool); 923 924/** Return a deep copy of @a log_entry, allocated in @a pool. 925 * 926 * The resulting svn_log_entry_t has @c changed_paths set to the same 927 * value as @c changed_path2. @c changed_paths will be @c NULL if 928 * @c changed_paths2 was @c NULL. 929 * 930 * @since New in 1.6. 931 */ 932svn_log_entry_t * 933svn_log_entry_dup(const svn_log_entry_t *log_entry, apr_pool_t *pool); 934 935/** The callback invoked by log message loopers, such as 936 * #svn_ra_plugin_t.get_log() and svn_repos_get_logs(). 937 * 938 * This function is invoked once on each log message, in the order 939 * determined by the caller (see above-mentioned functions). 940 * 941 * @a baton is what you think it is, and @a log_entry contains relevant 942 * information for the log message. Any of @a log_entry->author, 943 * @a log_entry->date, or @a log_entry->message may be @c NULL. 944 * 945 * If @a log_entry->date is neither NULL nor the empty string, it was 946 * generated by svn_time_to_cstring() and can be converted to 947 * @c apr_time_t with svn_time_from_cstring(). 948 * 949 * If @a log_entry->changed_paths is non-@c NULL, then it contains as keys 950 * every path committed in @a log_entry->revision; the values are 951 * (#svn_log_changed_path_t *) structures. 952 * 953 * If @a log_entry->has_children is @c TRUE, the message will be followed 954 * immediately by any number of merged revisions (child messages), which are 955 * terminated by an invocation with SVN_INVALID_REVNUM. This usage may 956 * be recursive. 957 * 958 * Use @a pool for temporary allocation. If the caller is iterating 959 * over log messages, invoking this receiver on each, we recommend the 960 * standard pool loop recipe: create a subpool, pass it as @a pool to 961 * each call, clear it after each iteration, destroy it after the loop 962 * is done. (For allocation that must last beyond the lifetime of a 963 * given receiver call, use a pool in @a baton.) 964 * 965 * @since New in 1.5. 966 */ 967typedef svn_error_t *(*svn_log_entry_receiver_t)( 968 void *baton, 969 svn_log_entry_t *log_entry, 970 apr_pool_t *pool); 971 972/** 973 * Similar to #svn_log_entry_receiver_t, except this uses separate 974 * parameters for each part of the log entry. 975 * 976 * @deprecated Provided for backward compatibility with the 1.4 API. 977 */ 978typedef svn_error_t *(*svn_log_message_receiver_t)( 979 void *baton, 980 apr_hash_t *changed_paths, 981 svn_revnum_t revision, 982 const char *author, 983 const char *date, /* use svn_time_from_cstring() if need apr_time_t */ 984 const char *message, 985 apr_pool_t *pool); 986 987 988/** Callback function type for commits. 989 * 990 * When a commit succeeds, an instance of this is invoked with the 991 * @a commit_info, along with the @a baton closure. 992 * @a pool can be used for temporary allocations. 993 * 994 * @note Implementers of this callback that pass this callback to 995 * svn_ra_get_commit_editor3() should be careful with returning errors 996 * as these might be returned as commit errors. See the documentation 997 * of svn_ra_get_commit_editor3() for more details. 998 * 999 * @since New in 1.4. 1000 */ 1001typedef svn_error_t *(*svn_commit_callback2_t)( 1002 const svn_commit_info_t *commit_info, 1003 void *baton, 1004 apr_pool_t *pool); 1005 1006/** Same as #svn_commit_callback2_t, but uses individual 1007 * data elements instead of the #svn_commit_info_t structure 1008 * 1009 * @deprecated Provided for backward compatibility with the 1.3 API. 1010 */ 1011typedef svn_error_t *(*svn_commit_callback_t)( 1012 svn_revnum_t new_revision, 1013 const char *date, 1014 const char *author, 1015 void *baton); 1016 1017 1018 1019/** A buffer size that may be used when processing a stream of data. 1020 * 1021 * @note We don't use this constant any longer, since it is considered to be 1022 * unnecessarily large. 1023 * 1024 * @deprecated Provided for backwards compatibility with the 1.3 API. 1025 */ 1026#define SVN_STREAM_CHUNK_SIZE 102400 1027 1028#ifndef DOXYGEN_SHOULD_SKIP_THIS 1029/* 1030 * The maximum amount we (ideally) hold in memory at a time when 1031 * processing a stream of data. 1032 * 1033 * For example, when copying data from one stream to another, do it in 1034 * blocks of this size. 1035 * 1036 * NOTE: This is an internal macro, put here for convenience. 1037 * No public API may depend on the particular value of this macro. 1038 */ 1039#define SVN__STREAM_CHUNK_SIZE 16384 1040#endif 1041 1042/** The maximum amount we can ever hold in memory. */ 1043/* FIXME: Should this be the same as SVN_STREAM_CHUNK_SIZE? */ 1044#define SVN_MAX_OBJECT_SIZE (((apr_size_t) -1) / 2) 1045 1046 1047 1048/* ### Note: despite being about mime-TYPES, these probably don't 1049 * ### belong in svn_types.h. However, no other header is more 1050 * ### appropriate, and didn't feel like creating svn_validate.h for 1051 * ### so little. 1052 */ 1053 1054/** Validate @a mime_type. 1055 * 1056 * If @a mime_type does not contain a "/", or ends with non-alphanumeric 1057 * data, return #SVN_ERR_BAD_MIME_TYPE, else return success. 1058 * 1059 * Use @a pool only to find error allocation. 1060 * 1061 * Goal: to match both "foo/bar" and "foo/bar; charset=blah", without 1062 * being too strict about it, but to disallow mime types that have 1063 * quotes, newlines, or other garbage on the end, such as might be 1064 * unsafe in an HTTP header. 1065 */ 1066svn_error_t * 1067svn_mime_type_validate(const char *mime_type, 1068 apr_pool_t *pool); 1069 1070/** Return FALSE iff @a mime_type is a textual type. 1071 * 1072 * All mime types that start with "text/" are textual, plus some special 1073 * cases (for example, "image/x-xbitmap"). 1074 */ 1075svn_boolean_t 1076svn_mime_type_is_binary(const char *mime_type); 1077 1078 1079 1080/** A user defined callback that subversion will call with a user defined 1081 * baton to see if the current operation should be continued. If the operation 1082 * should continue, the function should return #SVN_NO_ERROR, if not, it 1083 * should return #SVN_ERR_CANCELLED. 1084 */ 1085typedef svn_error_t *(*svn_cancel_func_t)(void *cancel_baton); 1086 1087 1088 1089/** 1090 * A lock object, for client & server to share. 1091 * 1092 * A lock represents the exclusive right to add, delete, or modify a 1093 * path. A lock is created in a repository, wholly controlled by the 1094 * repository. A "lock-token" is the lock's UUID, and can be used to 1095 * learn more about a lock's fields, and or/make use of the lock. 1096 * Because a lock is immutable, a client is free to not only cache the 1097 * lock-token, but the lock's fields too, for convenience. 1098 * 1099 * Note that the 'is_dav_comment' field is wholly ignored by every 1100 * library except for mod_dav_svn. The field isn't even marshalled 1101 * over the network to the client. Assuming lock structures are 1102 * created with apr_pcalloc(), a default value of 0 is universally safe. 1103 * 1104 * @note in the current implementation, only files are lockable. 1105 * 1106 * @since New in 1.2. 1107 */ 1108typedef struct svn_lock_t 1109{ 1110 const char *path; /**< the path this lock applies to */ 1111 const char *token; /**< unique URI representing lock */ 1112 const char *owner; /**< the username which owns the lock */ 1113 const char *comment; /**< (optional) description of lock */ 1114 svn_boolean_t is_dav_comment; /**< was comment made by generic DAV client? */ 1115 apr_time_t creation_date; /**< when lock was made */ 1116 apr_time_t expiration_date; /**< (optional) when lock will expire; 1117 If value is 0, lock will never expire. */ 1118} svn_lock_t; 1119 1120/** 1121 * Returns an #svn_lock_t, allocated in @a pool with all fields initialized 1122 * to NULL values. 1123 * 1124 * @note To allow for extending the #svn_lock_t structure in the future 1125 * releases, this function should always be used to allocate the structure. 1126 * 1127 * @since New in 1.2. 1128 */ 1129svn_lock_t * 1130svn_lock_create(apr_pool_t *pool); 1131 1132/** 1133 * Return a deep copy of @a lock, allocated in @a pool. 1134 * 1135 * @since New in 1.2. 1136 */ 1137svn_lock_t * 1138svn_lock_dup(const svn_lock_t *lock, apr_pool_t *pool); 1139 1140 1141 1142/** 1143 * Return a formatted Universal Unique IDentifier (UUID) string. 1144 * 1145 * @since New in 1.4. 1146 */ 1147const char * 1148svn_uuid_generate(apr_pool_t *pool); 1149 1150 1151 1152/** 1153 * Mergeinfo representing a merge of a range of revisions. 1154 * 1155 * @since New in 1.5 1156 */ 1157typedef struct svn_merge_range_t 1158{ 1159 /** 1160 * If the 'start' field is less than the 'end' field then 'start' is 1161 * exclusive and 'end' inclusive of the range described. This is termed 1162 * a forward merge range. If 'start' is greater than 'end' then the 1163 * opposite is true. This is termed a reverse merge range. If 'start' 1164 * equals 'end' the meaning of the range is not defined. 1165 */ 1166 svn_revnum_t start; 1167 svn_revnum_t end; 1168 1169 /** 1170 * Whether this merge range should be inherited by treewise 1171 * descendants of the path to which the range applies. */ 1172 svn_boolean_t inheritable; 1173} svn_merge_range_t; 1174 1175/** 1176 * Return a copy of @a range, allocated in @a pool. 1177 * 1178 * @since New in 1.5. 1179 */ 1180svn_merge_range_t * 1181svn_merge_range_dup(const svn_merge_range_t *range, apr_pool_t *pool); 1182 1183/** 1184 * Returns true if the changeset committed in revision @a rev is one 1185 * of the changesets in the range @a range. 1186 * 1187 * @since New in 1.5. 1188 */ 1189svn_boolean_t 1190svn_merge_range_contains_rev(const svn_merge_range_t *range, svn_revnum_t rev); 1191 1192 1193 1194/** @defgroup node_location_seg_reporting Node location segment reporting. 1195 * @{ */ 1196 1197/** 1198 * A representation of a segment of an object's version history with an 1199 * emphasis on the object's location in the repository as of various 1200 * revisions. 1201 * 1202 * @since New in 1.5. 1203 */ 1204typedef struct svn_location_segment_t 1205{ 1206 /** The beginning (oldest) and ending (youngest) revisions for this 1207 segment, both inclusive. */ 1208 svn_revnum_t range_start; 1209 svn_revnum_t range_end; 1210 1211 /** The absolute (sans leading slash) path for this segment. May be 1212 NULL to indicate gaps in an object's history. */ 1213 const char *path; 1214 1215} svn_location_segment_t; 1216 1217/** 1218 * A callback invoked by generators of #svn_location_segment_t 1219 * objects, used to report information about a versioned object's 1220 * history in terms of its location in the repository filesystem over 1221 * time. 1222 */ 1223typedef svn_error_t *(*svn_location_segment_receiver_t)( 1224 svn_location_segment_t *segment, 1225 void *baton, 1226 apr_pool_t *pool); 1227 1228/** 1229 * Return a deep copy of @a segment, allocated in @a pool. 1230 * 1231 * @since New in 1.5. 1232 */ 1233svn_location_segment_t * 1234svn_location_segment_dup(const svn_location_segment_t *segment, 1235 apr_pool_t *pool); 1236 1237/** @} */ 1238 1239 1240 1241/** A line number, such as in a file or a stream. 1242 * 1243 * @since New in 1.7. 1244 */ 1245typedef unsigned long svn_linenum_t; 1246 1247/** The maximum value of an svn_linenum_t. 1248 * 1249 * @since New in 1.7. 1250 */ 1251#define SVN_LINENUM_MAX_VALUE ULONG_MAX 1252 1253 1254 1255#ifdef __cplusplus 1256} 1257#endif /* __cplusplus */ 1258 1259 1260/* 1261 * Everybody and their brother needs to deal with svn_error_t, the error 1262 * codes, and whatever else. While they *should* go and include svn_error.h 1263 * in order to do that... bah. Let's just help everybody out and include 1264 * that header whenever somebody grabs svn_types.h. 1265 * 1266 * Note that we do this at the END of this header so that its contents 1267 * are available to svn_error.h (our guards will prevent the circular 1268 * include). We also need to do the include *outside* of the cplusplus 1269 * guard. 1270 */ 1271#include "svn_error.h" 1272 1273 1274/* 1275 * Subversion developers may want to use some additional debugging facilities 1276 * while working on the code. We'll pull that in here, so individual source 1277 * files don't have to include this header manually. 1278 */ 1279#ifdef SVN_DEBUG 1280#include "private/svn_debug.h" 1281#endif 1282 1283 1284#endif /* SVN_TYPES_H */ 1285