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