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