00001 /** 00002 * @copyright 00003 * ==================================================================== 00004 * Copyright (c) 2000-2004 CollabNet. All rights reserved. 00005 * 00006 * This software is licensed as described in the file COPYING, which 00007 * you should have received as part of this distribution. The terms 00008 * are also available at http://subversion.tigris.org/license-1.html. 00009 * If newer versions of this license are posted there, you may use a 00010 * newer version instead, at your option. 00011 * 00012 * This software consists of voluntary contributions made by many 00013 * individuals. For exact contribution history, see the revision 00014 * history and logs, available at http://subversion.tigris.org/. 00015 * ==================================================================== 00016 * @endcopyright 00017 * 00018 * @file svn_types.h 00019 * @brief Subversion's data types 00020 */ 00021 00022 #ifndef SVN_TYPES_H 00023 #define SVN_TYPES_H 00024 00025 /* ### this should go away, but it causes too much breakage right now */ 00026 #include <stdlib.h> 00027 00028 #include <apr.h> /* for apr_size_t */ 00029 #include <apr_pools.h> 00030 #include <apr_hash.h> 00031 #include <apr_tables.h> 00032 #include <apr_time.h> 00033 00034 #ifdef __cplusplus 00035 extern "C" { 00036 #endif /* __cplusplus */ 00037 00038 00039 00040 /** Subversion error object. 00041 * 00042 * Defined here, rather than in svn_error.h, to avoid a recursive @#include 00043 * situation. 00044 */ 00045 typedef struct svn_error_t 00046 { 00047 /** APR error value, possibly SVN_ custom err */ 00048 apr_status_t apr_err; 00049 00050 /** details from producer of error */ 00051 const char *message; 00052 00053 /** ptr to the error we "wrap" */ 00054 struct svn_error_t *child; 00055 00056 /** The pool holding this error and any child errors it wraps */ 00057 apr_pool_t *pool; 00058 00059 /** Source file where the error originated. Only used iff @c SVN_DEBUG. */ 00060 const char *file; 00061 00062 /** Source line where the error originated. Only used iff @c SVN_DEBUG. */ 00063 long line; 00064 00065 } svn_error_t; 00066 00067 00068 00069 /** @defgroup APR_ARRAY_compat_macros APR Array Compatibility Helper Macros 00070 * These macros are provided by APR itself from version 1.3. 00071 * Definitions are provided here for when using older versions of APR. 00072 * @{ 00073 */ 00074 00075 /** index into an apr_array_header_t */ 00076 #ifndef APR_ARRAY_IDX 00077 #define APR_ARRAY_IDX(ary,i,type) (((type *)(ary)->elts)[i]) 00078 #endif 00079 00080 /** easier array-pushing syntax */ 00081 #ifndef APR_ARRAY_PUSH 00082 #define APR_ARRAY_PUSH(ary,type) (*((type *)apr_array_push(ary))) 00083 #endif 00084 00085 /** @} */ 00086 00087 /** The various types of nodes in the Subversion filesystem. */ 00088 typedef enum 00089 { 00090 /* absent */ 00091 svn_node_none, 00092 00093 /* regular file */ 00094 svn_node_file, 00095 00096 /* directory */ 00097 svn_node_dir, 00098 00099 /* something's here, but we don't know what */ 00100 svn_node_unknown 00101 } svn_node_kind_t; 00102 00103 /** About Special Files in Subversion 00104 * 00105 * Subversion denotes files that cannot be portably created or 00106 * modified as "special" files (svn_node_special). It stores these 00107 * files in the repository as a plain text file with the svn:special 00108 * property set. The file contents contain: a platform-specific type 00109 * string, a space character, then any information necessary to create 00110 * the file on a supported platform. For example, if a symbolic link 00111 * were being represented, the repository file would have the 00112 * following contents: 00113 * 00114 * "link /path/to/link/target" 00115 * 00116 * Where 'link' is the identifier string showing that this special 00117 * file should be a symbolic link and '/path/to/link/target' is the 00118 * destination of the symbolic link. 00119 * 00120 * Special files are stored in the text-base exactly as they are 00121 * stored in the repository. The platform specific files are created 00122 * in the working copy at EOL/keyword translation time using 00123 * svn_subst_copy_and_translate2(). If the current platform does not 00124 * support a specific special file type, the file is copied into the 00125 * working copy as it is seen in the repository. Because of this, 00126 * users of other platforms can still view and modify the special 00127 * files, even if they do not have their unique properties. 00128 * 00129 * New types of special files can be added by: 00130 * 1. Implementing a platform-dependent routine to create a uniquely 00131 * named special file and one to read the special file in 00132 * libsvn_subr/io.c. 00133 * 2. Creating a new textual name similar to 00134 * SVN_SUBST__SPECIAL_LINK_STR in libsvn_subr/subst.c. 00135 * 3. Handling the translation/detranslation case for the new type in 00136 * create_special_file and detranslate_special_file, using the 00137 * routines from 1. 00138 */ 00139 00140 /** A revision number. */ 00141 typedef long int svn_revnum_t; 00142 00143 /** Valid revision numbers begin at 0 */ 00144 #define SVN_IS_VALID_REVNUM(n) ((n) >= 0) 00145 00146 /** The 'official' invalid revision num */ 00147 #define SVN_INVALID_REVNUM ((svn_revnum_t) -1) 00148 00149 /** Not really invalid...just unimportant -- one day, this can be its 00150 * own unique value, for now, just make it the same as 00151 * @c SVN_INVALID_REVNUM. 00152 */ 00153 #define SVN_IGNORED_REVNUM ((svn_revnum_t) -1) 00154 00155 /** Convert null-terminated C string @a str to a revision number. */ 00156 #define SVN_STR_TO_REV(str) ((svn_revnum_t) atol(str)) 00157 00158 /** In printf()-style functions, format revision numbers using this. 00159 * Do not use this macro within the Subversion project source code, because 00160 * the language translation tools have trouble parsing it. */ 00161 #define SVN_REVNUM_T_FMT "ld" 00162 00163 00164 /** The size of a file in the Subversion FS. */ 00165 typedef apr_int64_t svn_filesize_t; 00166 00167 /** The 'official' invalid file size constant. */ 00168 #define SVN_INVALID_FILESIZE ((svn_filesize_t) -1) 00169 00170 /** In printf()-style functions, format file sizes using this. */ 00171 #define SVN_FILESIZE_T_FMT APR_INT64_T_FMT 00172 00173 #ifndef DOXYGEN_SHOULD_SKIP_THIS 00174 /* Parse a base-10 numeric string into a 64-bit unsigned numeric value. */ 00175 /* NOTE: Private. For use by Subversion's own code only. See issue #1644. */ 00176 /* FIXME: APR should supply a function to do this, such as "apr_atoui64". */ 00177 #define svn__atoui64(X) ((apr_uint64_t) apr_atoi64(X)) 00178 #endif 00179 00180 00181 /** YABT: Yet Another Boolean Type */ 00182 typedef int svn_boolean_t; 00183 00184 #ifndef TRUE 00185 /** uhh... true */ 00186 #define TRUE 1 00187 #endif /* TRUE */ 00188 00189 #ifndef FALSE 00190 /** uhh... false */ 00191 #define FALSE 0 00192 #endif /* FALSE */ 00193 00194 00195 /** An enum to indicate whether recursion is needed. */ 00196 enum svn_recurse_kind 00197 { 00198 svn_nonrecursive = 1, 00199 svn_recursive 00200 }; 00201 00202 /** 00203 * It is sometimes convenient to indicate which parts of an @c svn_dirent_t 00204 * object you are actually interested in, so that calculating and sending 00205 * the data corresponding to the other fields can be avoided. These values 00206 * can be used for that purpose. 00207 * 00208 * @defgroup svn_dirent_fields dirent fields 00209 * @{ 00210 */ 00211 00212 /** An indication that you are interested in the @c kind field */ 00213 #define SVN_DIRENT_KIND 0x00001 00214 00215 /** An indication that you are interested in the @c size field */ 00216 #define SVN_DIRENT_SIZE 0x00002 00217 00218 /** An indication that you are interested in the @c has_props field */ 00219 #define SVN_DIRENT_HAS_PROPS 0x00004 00220 00221 /** An indication that you are interested in the @c created_rev field */ 00222 #define SVN_DIRENT_CREATED_REV 0x00008 00223 00224 /** An indication that you are interested in the @c time field */ 00225 #define SVN_DIRENT_TIME 0x00010 00226 00227 /** An indication that you are interested in the @c last_author field */ 00228 #define SVN_DIRENT_LAST_AUTHOR 0x00020 00229 00230 /** A combination of all the dirent fields */ 00231 #define SVN_DIRENT_ALL ~((apr_uint32_t ) 0) 00232 00233 /** @} */ 00234 00235 /** A general subversion directory entry. */ 00236 typedef struct svn_dirent_t 00237 { 00238 /** node kind */ 00239 svn_node_kind_t kind; 00240 00241 /** length of file text, or 0 for directories */ 00242 svn_filesize_t size; 00243 00244 /** does the node have props? */ 00245 svn_boolean_t has_props; 00246 00247 /** last rev in which this node changed */ 00248 svn_revnum_t created_rev; 00249 00250 /** time of created_rev (mod-time) */ 00251 apr_time_t time; 00252 00253 /** author of created_rev */ 00254 const char *last_author; 00255 00256 /* IMPORTANT: If you extend this struct, check svn_dirent_dup(). */ 00257 } svn_dirent_t; 00258 00259 00260 /** Return a deep copy of @a dirent, allocated in @a pool. 00261 * 00262 * @since New in 1.4. 00263 */ 00264 svn_dirent_t *svn_dirent_dup(const svn_dirent_t *dirent, 00265 apr_pool_t *pool); 00266 00267 00268 00269 /** Keyword substitution. 00270 * 00271 * All the keywords Subversion recognizes. 00272 * 00273 * Note that there is a better, more general proposal out there, which 00274 * would take care of both internationalization issues and custom 00275 * keywords (e.g., $NetBSD$). See 00276 * 00277 *<pre> http://subversion.tigris.org/servlets/ReadMsg?list=dev&msgNo=8921 00278 * ===== 00279 * From: "Jonathan M. Manning" <jmanning@alisa-jon.net> 00280 * To: dev@subversion.tigris.org 00281 * Date: Fri, 14 Dec 2001 11:56:54 -0500 00282 * Message-ID: <87970000.1008349014@bdldevel.bl.bdx.com> 00283 * Subject: Re: keywords</pre> 00284 * 00285 * and Eric Gillespie's support of same: 00286 * 00287 *<pre> http://subversion.tigris.org/servlets/ReadMsg?list=dev&msgNo=8757 00288 * ===== 00289 * From: "Eric Gillespie, Jr." <epg@pretzelnet.org> 00290 * To: dev@subversion.tigris.org 00291 * Date: Wed, 12 Dec 2001 09:48:42 -0500 00292 * Message-ID: <87k7vsebp1.fsf@vger.pretzelnet.org> 00293 * Subject: Re: Customizable Keywords</pre> 00294 * 00295 * However, it is considerably more complex than the scheme below. 00296 * For now we're going with simplicity, hopefully the more general 00297 * solution can be done post-1.0. 00298 * 00299 * @defgroup svn_types_keywords keywords 00300 * @{ 00301 */ 00302 00303 /** The maximum size of an expanded or un-expanded keyword. */ 00304 #define SVN_KEYWORD_MAX_LEN 255 00305 00306 /** The most recent revision in which this file was changed. */ 00307 #define SVN_KEYWORD_REVISION_LONG "LastChangedRevision" 00308 00309 /** Short version of LastChangedRevision */ 00310 #define SVN_KEYWORD_REVISION_SHORT "Rev" 00311 00312 /** Medium version of LastChangedRevision, matching the one CVS uses. 00313 * @since New in 1.1. */ 00314 #define SVN_KEYWORD_REVISION_MEDIUM "Revision" 00315 00316 /** The most recent date (repository time) when this file was changed. */ 00317 #define SVN_KEYWORD_DATE_LONG "LastChangedDate" 00318 00319 /** Short version of LastChangedDate */ 00320 #define SVN_KEYWORD_DATE_SHORT "Date" 00321 00322 /** Who most recently committed to this file. */ 00323 #define SVN_KEYWORD_AUTHOR_LONG "LastChangedBy" 00324 00325 /** Short version of LastChangedBy */ 00326 #define SVN_KEYWORD_AUTHOR_SHORT "Author" 00327 00328 /** The URL for the head revision of this file. */ 00329 #define SVN_KEYWORD_URL_LONG "HeadURL" 00330 00331 /** Short version of HeadURL */ 00332 #define SVN_KEYWORD_URL_SHORT "URL" 00333 00334 /** A compressed combination of the other four keywords. */ 00335 #define SVN_KEYWORD_ID "Id" 00336 00337 /** @} */ 00338 00339 00340 /** All information about a commit. 00341 * 00342 * @note Objects of this type should always be created using the 00343 * svn_create_commit_info() function. 00344 * 00345 * @since New in 1.3. 00346 */ 00347 typedef struct svn_commit_info_t 00348 { 00349 /** just-committed revision. */ 00350 svn_revnum_t revision; 00351 00352 /** server-side date of the commit. */ 00353 const char *date; 00354 00355 /** author of the commit. */ 00356 const char *author; 00357 00358 /** error message from post-commit hook, or NULL. */ 00359 const char *post_commit_err; 00360 00361 } svn_commit_info_t; 00362 00363 00364 /** 00365 * Allocate an object of type @c svn_commit_info_t in @a pool and 00366 * return it. 00367 * 00368 * The @c revision field of the new struct is set to @c 00369 * SVN_INVALID_REVNUM. All other fields are initialized to @c NULL. 00370 * 00371 * @note Any object of the type @c svn_commit_info_t should 00372 * be created using this function. 00373 * This is to provide for extending the svn_commit_info_t in 00374 * the future. 00375 * 00376 * @since New in 1.3. 00377 */ 00378 svn_commit_info_t * 00379 svn_create_commit_info(apr_pool_t *pool); 00380 00381 00382 /** 00383 * Return a deep copy @a src_commit_info allocated in @a pool. 00384 * 00385 * @since New in 1.4. 00386 */ 00387 svn_commit_info_t * 00388 svn_commit_info_dup(const svn_commit_info_t *src_commit_info, 00389 apr_pool_t *pool); 00390 00391 00392 /** A structure to represent a path that changed for a log entry. */ 00393 typedef struct svn_log_changed_path_t 00394 { 00395 /** 'A'dd, 'D'elete, 'R'eplace, 'M'odify */ 00396 char action; 00397 00398 /** Source path of copy (if any). */ 00399 const char *copyfrom_path; 00400 00401 /** Source revision of copy (if any). */ 00402 svn_revnum_t copyfrom_rev; 00403 00404 } svn_log_changed_path_t; 00405 00406 00407 /** 00408 * Return a deep copy of @a changed_path, allocated in @a pool. 00409 * 00410 * @since New in 1.3. 00411 */ 00412 svn_log_changed_path_t * 00413 svn_log_changed_path_dup(const svn_log_changed_path_t *changed_path, 00414 apr_pool_t *pool); 00415 00416 00417 /** The callback invoked by log message loopers, such as 00418 * @c svn_ra_plugin_t.get_log() and svn_repos_get_logs(). 00419 * 00420 * This function is invoked once on each log message, in the order 00421 * determined by the caller (see above-mentioned functions). 00422 * 00423 * @a baton, @a revision, @a author, @a date, and @a message are what you 00424 * think they are. Any of @a author, @a date, or @a message may be @c NULL. 00425 * 00426 * If @a date is neither null nor the empty string, it was generated by 00427 * svn_time_to_string() and can be converted to @c apr_time_t with 00428 * svn_time_from_string(). 00429 * 00430 * If @a changed_paths is non-@c NULL, then it contains as keys every path 00431 * committed in @a revision; the values are (@c svn_log_changed_path_t *) 00432 * structures. 00433 * 00434 * ### The only reason @a changed_paths is not qualified with `const' is 00435 * that we usually want to loop over it, and apr_hash_first() doesn't 00436 * take a const hash, for various reasons. I'm not sure that those 00437 * "various reasons" are actually even relevant anymore, and if 00438 * they're not, it might be nice to change apr_hash_first() so 00439 * read-only uses of hashes can be protected via the type system. 00440 * 00441 * Use @a pool for all allocation. (If the caller is iterating over log 00442 * messages, invoking this receiver on each, we recommend the standard 00443 * pool loop recipe: create a subpool, pass it as @a pool to each call, 00444 * clear it after each iteration, destroy it after the loop is done.) 00445 */ 00446 typedef svn_error_t *(*svn_log_message_receiver_t) 00447 (void *baton, 00448 apr_hash_t *changed_paths, 00449 svn_revnum_t revision, 00450 const char *author, 00451 const char *date, /* use svn_time_from_string() if need apr_time_t */ 00452 const char *message, 00453 apr_pool_t *pool); 00454 00455 00456 /** Callback function type for commits. 00457 * 00458 * When a commit succeeds, an instance of this is invoked with the 00459 * @a commit_info, along with the @a baton closure. 00460 * @a pool can be used for temporary allocations. 00461 * 00462 * @since New in 1.4. 00463 */ 00464 typedef svn_error_t *(*svn_commit_callback2_t) 00465 (const svn_commit_info_t *commit_info, 00466 void *baton, 00467 apr_pool_t *pool); 00468 00469 /** Same as @c svn_commit_callback2_t, but uses individual 00470 * data elements instead of the @c svn_commit_info_t structure 00471 * 00472 * @deprecated Provided for backward compatibility with the 1.3 API. 00473 */ 00474 typedef svn_error_t *(*svn_commit_callback_t) 00475 (svn_revnum_t new_revision, 00476 const char *date, 00477 const char *author, 00478 void *baton); 00479 00480 00481 /** Return, in @a *callback2 and @a *callback2_baton a function/baton that 00482 * will call @a callback/@a callback_baton, allocating the @a *callback2_baton 00483 * in @a pool. 00484 * 00485 * @note This is used by compatibility wrappers, which exist in more than 00486 * Subversion core library. 00487 * 00488 * @since New in 1.4. 00489 */ 00490 void svn_compat_wrap_commit_callback(svn_commit_callback2_t *callback2, 00491 void **callback2_baton, 00492 svn_commit_callback_t callback, 00493 void *callback_baton, 00494 apr_pool_t *pool); 00495 00496 00497 /** A buffer size that may be used when processing a stream of data. 00498 * 00499 * @note We don't use this constant any longer, since it is considered to be 00500 * unnecessarily large. 00501 * 00502 * @deprecated Provided for backwards compatibility with the 1.3 API. 00503 */ 00504 #define SVN_STREAM_CHUNK_SIZE 102400 00505 00506 #ifndef DOXYGEN_SHOULD_SKIP_THIS 00507 /* 00508 * The maximum amount we (ideally) hold in memory at a time when 00509 * processing a stream of data. 00510 * 00511 * For example, when copying data from one stream to another, do it in 00512 * blocks of this size. 00513 * 00514 * NOTE: This is an internal macro, put here for convenience. 00515 * No public API may depend on the particular value of this macro. 00516 */ 00517 #define SVN__STREAM_CHUNK_SIZE 16384 00518 #endif 00519 00520 /** The maximum amount we can ever hold in memory. */ 00521 /* FIXME: Should this be the same as SVN_STREAM_CHUNK_SIZE? */ 00522 #define SVN_MAX_OBJECT_SIZE (((apr_size_t) -1) / 2) 00523 00524 00525 00526 /* ### Note: despite being about mime-TYPES, these probably don't 00527 * ### belong in svn_types.h. However, no other header is more 00528 * ### appropriate, and didn't feel like creating svn_validate.h for 00529 * ### so little. 00530 */ 00531 00532 /** Validate @a mime_type. 00533 * 00534 * If @a mime_type does not contain a "/", or ends with non-alphanumeric 00535 * data, return @c SVN_ERR_BAD_MIME_TYPE, else return success. 00536 * 00537 * Use @a pool only to find error allocation. 00538 * 00539 * Goal: to match both "foo/bar" and "foo/bar; charset=blah", without 00540 * being too strict about it, but to disallow mime types that have 00541 * quotes, newlines, or other garbage on the end, such as might be 00542 * unsafe in an HTTP header. 00543 */ 00544 svn_error_t *svn_mime_type_validate(const char *mime_type, 00545 apr_pool_t *pool); 00546 00547 00548 /** Return false iff @a mime_type is a textual type. 00549 * 00550 * All mime types that start with "text/" are textual, plus some special 00551 * cases (for example, "image/x-xbitmap"). 00552 */ 00553 svn_boolean_t svn_mime_type_is_binary(const char *mime_type); 00554 00555 00556 00557 /** A user defined callback that subversion will call with a user defined 00558 * baton to see if the current operation should be continued. If the operation 00559 * should continue, the function should return @c SVN_NO_ERROR, if not, it 00560 * should return @c SVN_ERR_CANCELLED. 00561 */ 00562 typedef svn_error_t *(*svn_cancel_func_t)(void *cancel_baton); 00563 00564 00565 00566 /** 00567 * A lock object, for client & server to share. 00568 * 00569 * A lock represents the exclusive right to add, delete, or modify a 00570 * path. A lock is created in a repository, wholly controlled by the 00571 * repository. A "lock-token" is the lock's UUID, and can be used to 00572 * learn more about a lock's fields, and or/make use of the lock. 00573 * Because a lock is immutable, a client is free to not only cache the 00574 * lock-token, but the lock's fields too, for convenience. 00575 * 00576 * Note that the 'is_dav_comment' field is wholly ignored by every 00577 * library except for mod_dav_svn. The field isn't even marshalled 00578 * over the network to the client. Assuming lock structures are 00579 * created with apr_pcalloc(), a default value of 0 is universally safe. 00580 * 00581 * @note in the current implementation, only files are lockable. 00582 * 00583 * @since New in 1.2. 00584 */ 00585 typedef struct svn_lock_t 00586 { 00587 const char *path; /**< the path this lock applies to */ 00588 const char *token; /**< unique URI representing lock */ 00589 const char *owner; /**< the username which owns the lock */ 00590 const char *comment; /**< (optional) description of lock */ 00591 svn_boolean_t is_dav_comment; /**< was comment made by generic DAV client? */ 00592 apr_time_t creation_date; /**< when lock was made */ 00593 apr_time_t expiration_date; /**< (optional) when lock will expire; 00594 If value is 0, lock will never expire. */ 00595 } svn_lock_t; 00596 00597 /** 00598 * Returns an @c svn_lock_t, allocated in @a pool with all fields initialized 00599 * to null values. 00600 * 00601 * @note To allow for extending the @c svn_lock_t structure in the future 00602 * releases, this function should always be used to allocate the structure. 00603 * 00604 * @since New in 1.2. 00605 */ 00606 svn_lock_t * 00607 svn_lock_create(apr_pool_t *pool); 00608 00609 /** 00610 * Return a deep copy of @a lock, allocated in @a pool. 00611 * 00612 * @since New in 1.2. 00613 */ 00614 svn_lock_t * 00615 svn_lock_dup(const svn_lock_t *lock, apr_pool_t *pool); 00616 00617 /** 00618 * Return a formatted Universal Unique IDentifier (UUID) string. 00619 * 00620 * @since New in 1.4. 00621 */ 00622 const char * 00623 svn_uuid_generate(apr_pool_t *pool); 00624 00625 #ifdef __cplusplus 00626 } 00627 #endif /* __cplusplus */ 00628 00629 #endif /* SVN_TYPES_H */