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 /** A general subversion directory entry. */ 00204 typedef struct svn_dirent_t 00205 { 00206 /** node kind */ 00207 svn_node_kind_t kind; 00208 00209 /** length of file text, or 0 for directories */ 00210 svn_filesize_t size; 00211 00212 /** does the node have props? */ 00213 svn_boolean_t has_props; 00214 00215 /** last rev in which this node changed */ 00216 svn_revnum_t created_rev; 00217 00218 /** time of created_rev (mod-time) */ 00219 apr_time_t time; 00220 00221 /** author of created_rev */ 00222 const char *last_author; 00223 00224 } svn_dirent_t; 00225 00226 00227 00228 00229 /** Keyword substitution. 00230 * 00231 * All the keywords Subversion recognizes. 00232 * 00233 * Note that there is a better, more general proposal out there, which 00234 * would take care of both internationalization issues and custom 00235 * keywords (e.g., $NetBSD$). See 00236 * 00237 *<pre> http://subversion.tigris.org/servlets/ReadMsg?list=dev&msgNo=8921 00238 * ===== 00239 * From: "Jonathan M. Manning" <jmanning@alisa-jon.net> 00240 * To: dev@subversion.tigris.org 00241 * Date: Fri, 14 Dec 2001 11:56:54 -0500 00242 * Message-ID: <87970000.1008349014@bdldevel.bl.bdx.com> 00243 * Subject: Re: keywords</pre> 00244 * 00245 * and Eric Gillespie's support of same: 00246 * 00247 *<pre> http://subversion.tigris.org/servlets/ReadMsg?list=dev&msgNo=8757 00248 * ===== 00249 * From: "Eric Gillespie, Jr." <epg@pretzelnet.org> 00250 * To: dev@subversion.tigris.org 00251 * Date: Wed, 12 Dec 2001 09:48:42 -0500 00252 * Message-ID: <87k7vsebp1.fsf@vger.pretzelnet.org> 00253 * Subject: Re: Customizable Keywords</pre> 00254 * 00255 * However, it is considerably more complex than the scheme below. 00256 * For now we're going with simplicity, hopefully the more general 00257 * solution can be done post-1.0. 00258 * 00259 * @defgroup svn_types_keywords keywords 00260 * @{ 00261 */ 00262 00263 /** The maximum size of an expanded or un-expanded keyword. */ 00264 #define SVN_KEYWORD_MAX_LEN 255 00265 00266 /** The most recent revision in which this file was changed. */ 00267 #define SVN_KEYWORD_REVISION_LONG "LastChangedRevision" 00268 00269 /** Short version of LastChangedRevision */ 00270 #define SVN_KEYWORD_REVISION_SHORT "Rev" 00271 00272 /** Medium version of LastChangedRevision, matching the one CVS uses. 00273 * @since New in 1.1. */ 00274 #define SVN_KEYWORD_REVISION_MEDIUM "Revision" 00275 00276 /** The most recent date (repository time) when this file was changed. */ 00277 #define SVN_KEYWORD_DATE_LONG "LastChangedDate" 00278 00279 /** Short version of LastChangedDate */ 00280 #define SVN_KEYWORD_DATE_SHORT "Date" 00281 00282 /** Who most recently committed to this file. */ 00283 #define SVN_KEYWORD_AUTHOR_LONG "LastChangedBy" 00284 00285 /** Short version of LastChangedBy */ 00286 #define SVN_KEYWORD_AUTHOR_SHORT "Author" 00287 00288 /** The URL for the head revision of this file. */ 00289 #define SVN_KEYWORD_URL_LONG "HeadURL" 00290 00291 /** Short version of HeadURL */ 00292 #define SVN_KEYWORD_URL_SHORT "URL" 00293 00294 /** A compressed combination of the other four keywords. */ 00295 #define SVN_KEYWORD_ID "Id" 00296 00297 /** @} */ 00298 00299 00300 /** All information about a commit. 00301 * 00302 * @note Objects of this type should always be created using the 00303 * svn_create_commit_info() function. 00304 * 00305 * @since New in 1.3. 00306 */ 00307 typedef struct svn_commit_info_t 00308 { 00309 /** just-committed revision. */ 00310 svn_revnum_t revision; 00311 00312 /** server-side date of the commit. */ 00313 const char *date; 00314 00315 /** author of the commit. */ 00316 const char *author; 00317 00318 /** error message from post-commit hook, or NULL. */ 00319 const char *post_commit_err; 00320 00321 } svn_commit_info_t; 00322 00323 00324 /** 00325 * Allocate an object of type @c svn_commit_info_t in @a pool and 00326 * return it. 00327 * 00328 * The @c revision field of the new struct is set to @c 00329 * SVN_INVALID_REVNUM. All other fields are initialized to @c NULL. 00330 * 00331 * @note Any object of the type @c svn_commit_info_t should 00332 * be created using this function. 00333 * This is to provide for extending the svn_commit_info_t in 00334 * the future. 00335 * 00336 * @since New in 1.3. 00337 */ 00338 svn_commit_info_t * 00339 svn_create_commit_info (apr_pool_t *pool); 00340 00341 00342 /** A structure to represent a path that changed for a log entry. */ 00343 typedef struct svn_log_changed_path_t 00344 { 00345 /** 'A'dd, 'D'elete, 'R'eplace, 'M'odify */ 00346 char action; 00347 00348 /** Source path of copy (if any). */ 00349 const char *copyfrom_path; 00350 00351 /** Source revision of copy (if any). */ 00352 svn_revnum_t copyfrom_rev; 00353 00354 } svn_log_changed_path_t; 00355 00356 00357 /** 00358 * Return a deep copy of @a changed_path, allocated in @a pool. 00359 * 00360 * @since New in 1.3. 00361 */ 00362 svn_log_changed_path_t *svn_log_changed_path_dup ( 00363 const svn_log_changed_path_t *changed_path, apr_pool_t *pool); 00364 00365 00366 /** The callback invoked by log message loopers, such as 00367 * @c svn_ra_plugin_t.get_log() and svn_repos_get_logs(). 00368 * 00369 * This function is invoked once on each log message, in the order 00370 * determined by the caller (see above-mentioned functions). 00371 * 00372 * @a baton, @a revision, @a author, @a date, and @a message are what you 00373 * think they are. Any of @a author, @a date, or @a message may be @c NULL. 00374 * 00375 * If @a date is neither null nor the empty string, it was generated by 00376 * svn_time_to_string() and can be converted to @c apr_time_t with 00377 * svn_time_from_string(). 00378 * 00379 * If @a changed_paths is non-@c NULL, then it contains as keys every path 00380 * committed in @a revision; the values are (@c svn_log_changed_path_t *) 00381 * structures. 00382 * 00383 * ### The only reason @a changed_paths is not qualified with `const' is 00384 * that we usually want to loop over it, and apr_hash_first() doesn't 00385 * take a const hash, for various reasons. I'm not sure that those 00386 * "various reasons" are actually even relevant anymore, and if 00387 * they're not, it might be nice to change apr_hash_first() so 00388 * read-only uses of hashes can be protected via the type system. 00389 * 00390 * Use @a pool for all allocation. (If the caller is iterating over log 00391 * messages, invoking this receiver on each, we recommend the standard 00392 * pool loop recipe: create a subpool, pass it as @a pool to each call, 00393 * clear it after each iteration, destroy it after the loop is done.) 00394 */ 00395 typedef svn_error_t *(*svn_log_message_receiver_t) 00396 (void *baton, 00397 apr_hash_t *changed_paths, 00398 svn_revnum_t revision, 00399 const char *author, 00400 const char *date, /* use svn_time_from_string() if need apr_time_t */ 00401 const char *message, 00402 apr_pool_t *pool); 00403 00404 00405 /** Callback function type for commits. 00406 * 00407 * When a commit succeeds, an instance of this is invoked on the @a 00408 * new_revision, @a date, and @a author of the commit, along with the 00409 * @a baton closure. 00410 */ 00411 typedef svn_error_t * (*svn_commit_callback_t) ( 00412 svn_revnum_t new_revision, 00413 const char *date, 00414 const char *author, 00415 void *baton); 00416 00417 00418 /** The maximum amount we (ideally) hold in memory at a time when 00419 * processing a stream of data. 00420 * 00421 * For example, when copying data from one stream to another, do it in 00422 * blocks of this size. 00423 */ 00424 #define SVN_STREAM_CHUNK_SIZE 102400 00425 00426 /** The maximum amount we can ever hold in memory. */ 00427 /* FIXME: Should this be the same as SVN_STREAM_CHUNK_SIZE? */ 00428 #define SVN_MAX_OBJECT_SIZE (((apr_size_t) -1) / 2) 00429 00430 00431 00432 /* ### Note: despite being about mime-TYPES, these probably don't 00433 * ### belong in svn_types.h. However, no other header is more 00434 * ### appropriate, and didn't feel like creating svn_validate.h for 00435 * ### so little. 00436 */ 00437 00438 /** Validate @a mime_type. 00439 * 00440 * If @a mime_type does not contain a "/", or ends with non-alphanumeric 00441 * data, return @c SVN_ERR_BAD_MIME_TYPE, else return success. 00442 * 00443 * Use @a pool only to find error allocation. 00444 * 00445 * Goal: to match both "foo/bar" and "foo/bar; charset=blah", without 00446 * being too strict about it, but to disallow mime types that have 00447 * quotes, newlines, or other garbage on the end, such as might be 00448 * unsafe in an HTTP header. 00449 */ 00450 svn_error_t *svn_mime_type_validate (const char *mime_type, 00451 apr_pool_t *pool); 00452 00453 00454 /** Return false iff @a mime_type is a textual type. 00455 * 00456 * All mime types that start with "text/" are textual, plus some special 00457 * cases (for example, "image/x-xbitmap"). 00458 */ 00459 svn_boolean_t svn_mime_type_is_binary (const char *mime_type); 00460 00461 00462 00463 /** A user defined callback that subversion will call with a user defined 00464 * baton to see if the current operation should be continued. If the operation 00465 * should continue, the function should return @c SVN_NO_ERROR, if not, it 00466 * should return @c SVN_ERR_CANCELLED. 00467 */ 00468 typedef svn_error_t *(*svn_cancel_func_t) (void *cancel_baton); 00469 00470 00471 00472 /** 00473 * A lock object, for client & server to share. 00474 * 00475 * A lock represents the exclusive right to add, delete, or modify a 00476 * path. A lock is created in a repository, wholly controlled by the 00477 * repository. A "lock-token" is the lock's UUID, and can be used to 00478 * learn more about a lock's fields, and or/make use of the lock. 00479 * Because a lock is immutable, a client is free to not only cache the 00480 * lock-token, but the lock's fields too, for convenience. 00481 * 00482 * Note that the 'is_dav_comment' field is wholly ignored by every 00483 * library except for mod_dav_svn. The field isn't even marshalled 00484 * over the network to the client. Assuming lock structures are 00485 * created with apr_pcalloc(), a default value of 0 is universally safe. 00486 * 00487 * @note in the current implementation, only files are lockable. 00488 * 00489 * @since New in 1.2. 00490 */ 00491 typedef struct svn_lock_t 00492 { 00493 const char *path; /**< the path this lock applies to */ 00494 const char *token; /**< unique URI representing lock */ 00495 const char *owner; /**< the username which owns the lock */ 00496 const char *comment; /**< (optional) description of lock */ 00497 svn_boolean_t is_dav_comment; /**< was comment made by generic DAV client? */ 00498 apr_time_t creation_date; /**< when lock was made */ 00499 apr_time_t expiration_date; /**< (optional) when lock will expire; 00500 If value is 0, lock will never expire. */ 00501 } svn_lock_t; 00502 00503 /** 00504 * Returns an @c svn_lock_t, allocated in @a pool with all fields initialized 00505 * to null values. 00506 * 00507 * @note To allow for extending the @c svn_lock_t structure in the future 00508 * releases, this function should always be used to allocate the structure. 00509 * 00510 * @since New in 1.2. 00511 */ 00512 svn_lock_t * 00513 svn_lock_create (apr_pool_t *pool); 00514 00515 /** 00516 * Return a deep copy of @a lock, allocated in @a pool. 00517 * 00518 * @since New in 1.2. 00519 */ 00520 svn_lock_t * 00521 svn_lock_dup (const svn_lock_t *lock, apr_pool_t *pool); 00522 00523 #ifdef __cplusplus 00524 } 00525 #endif /* __cplusplus */ 00526 00527 #endif /* SVN_TYPES_H */