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 /** index into an apr_array_header_t */ 00070 #ifndef APR_ARRAY_IDX 00071 #define APR_ARRAY_IDX(ary,i,type) (((type *)(ary)->elts)[i]) 00072 #endif 00073 00074 /** easier array-pushing syntax */ 00075 #ifndef APR_ARRAY_PUSH 00076 #define APR_ARRAY_PUSH(ary,type) (*((type *)apr_array_push (ary))) 00077 #endif 00078 00079 00080 /** The various types of nodes in the Subversion filesystem. */ 00081 typedef enum 00082 { 00083 /* absent */ 00084 svn_node_none, 00085 00086 /* regular file */ 00087 svn_node_file, 00088 00089 /* directory */ 00090 svn_node_dir, 00091 00092 /* something's here, but we don't know what */ 00093 svn_node_unknown 00094 } svn_node_kind_t; 00095 00096 /** About Special Files in Subversion 00097 * 00098 * Subversion denotes files that cannot be portably created or 00099 * modified as special files (svn_node_special). It stores these 00100 * files in the repository as a plain text file with the svn:special 00101 * property set. The file contents contain: a platform-specific type 00102 * string, a space character, then any information necessary to create 00103 * the file on a supported platform. For example, if a symbolic link 00104 * were being represented, the repository file would have the 00105 * following contents: 00106 * 00107 * "link /path/to/link/target" 00108 * 00109 * Where 'link' is the identifier string showing that this special 00110 * file should be a symbolic link and '/path/to/link/target' is the 00111 * destination of the symbolic link. 00112 * 00113 * Special files are stored in the text-base exactly as they are 00114 * stored in the repository. The platform specific files are created 00115 * in the working copy at EOL/keyword translation time using 00116 * svn_subst_copy_and_translate2. If the current platform does not 00117 * support a specific special file type, the file is copied into the 00118 * working copy as it is seen in the repository. Because of this, 00119 * users of other platforms can still view and modify the special 00120 * files, even if they do not have their unique properties. 00121 * 00122 * New types of special files can be added by: 00123 * 1. Implementing a platform-dependent routine to create a uniquely 00124 * named special file and one to read the special file in 00125 * libsvn_subr/io.c. 00126 * 2. Creating a new textual name similar to 00127 * SVN_SUBST__SPECIAL_LINK_STR in libsvn_subr/subst.c. 00128 * 3. Handling the translation/detranslation case for the new type in 00129 * create_special_file and detranslate_special_file, using the 00130 * routines from 1. 00131 */ 00132 00133 /** A revision number. */ 00134 typedef long int svn_revnum_t; 00135 00136 /** Valid revision numbers begin at 0 */ 00137 #define SVN_IS_VALID_REVNUM(n) ((n) >= 0) 00138 00139 /** The 'official' invalid revision num */ 00140 #define SVN_INVALID_REVNUM ((svn_revnum_t) -1) 00141 00142 /** Not really invalid...just unimportant -- one day, this can be its 00143 * own unique value, for now, just make it the same as 00144 * @c SVN_INVALID_REVNUM. 00145 */ 00146 #define SVN_IGNORED_REVNUM ((svn_revnum_t) -1) 00147 00148 /** Convert null-terminated C string @a str to a revision number. */ 00149 #define SVN_STR_TO_REV(str) ((svn_revnum_t) atol(str)) 00150 00151 /** In @c printf()-style functions, format revision numbers using this. 00152 * Do not use this macro within the Subversion project source code, because 00153 * the language translation tools have trouble parsing it. */ 00154 #define SVN_REVNUM_T_FMT "ld" 00155 00156 00157 /** The size of a file in the Subversion FS. */ 00158 typedef apr_int64_t svn_filesize_t; 00159 00160 /** The 'official' invalid file size constant. */ 00161 #define SVN_INVALID_FILESIZE ((svn_filesize_t) -1) 00162 00163 /** In @c printf()-style functions, format file sizes using this. */ 00164 #define SVN_FILESIZE_T_FMT APR_INT64_T_FMT 00165 00166 #ifndef DOXYGEN_SHOULD_SKIP_THIS 00167 /* Parse a base-10 numeric string into a 64-bit unsigned numeric value. */ 00168 /* NOTE: Private. For use by Subversion's own code only. See issue #1644. */ 00169 /* FIXME: APR should supply a function to do this, such as "apr_atoui64". */ 00170 #define svn__atoui64(X) ((apr_uint64_t) apr_atoi64(X)) 00171 #endif 00172 00173 00174 /** YABT: Yet Another Boolean Type */ 00175 typedef int svn_boolean_t; 00176 00177 #ifndef TRUE 00178 /** uhh... true */ 00179 #define TRUE 1 00180 #endif /* TRUE */ 00181 00182 #ifndef FALSE 00183 /** uhh... false */ 00184 #define FALSE 0 00185 #endif /* FALSE */ 00186 00187 00188 /** An enum to indicate whether recursion is needed. */ 00189 enum svn_recurse_kind 00190 { 00191 svn_nonrecursive = 1, 00192 svn_recursive 00193 }; 00194 00195 00196 /** A general subversion directory entry. */ 00197 typedef struct svn_dirent_t 00198 { 00199 /** node kind */ 00200 svn_node_kind_t kind; 00201 00202 /** length of file text, or 0 for directories */ 00203 svn_filesize_t size; 00204 00205 /** does the node have props? */ 00206 svn_boolean_t has_props; 00207 00208 /** last rev in which this node changed */ 00209 svn_revnum_t created_rev; 00210 00211 /** time of created_rev (mod-time) */ 00212 apr_time_t time; 00213 00214 /** author of created_rev */ 00215 const char *last_author; 00216 00217 } svn_dirent_t; 00218 00219 00220 00221 00222 /** Keyword substitution. 00223 * 00224 * All the keywords Subversion recognizes. 00225 * 00226 * Note that there is a better, more general proposal out there, which 00227 * would take care of both internationalization issues and custom 00228 * keywords (e.g., $NetBSD$). See 00229 * 00230 *<pre> http://subversion.tigris.org/servlets/ReadMsg?list=dev&msgNo=8921 00231 * ===== 00232 * From: "Jonathan M. Manning" <jmanning@alisa-jon.net> 00233 * To: dev@subversion.tigris.org 00234 * Date: Fri, 14 Dec 2001 11:56:54 -0500 00235 * Message-ID: <87970000.1008349014@bdldevel.bl.bdx.com> 00236 * Subject: Re: keywords</pre> 00237 * 00238 * and Eric Gillespie's support of same: 00239 * 00240 *<pre> http://subversion.tigris.org/servlets/ReadMsg?list=dev&msgNo=8757 00241 * ===== 00242 * From: "Eric Gillespie, Jr." <epg@pretzelnet.org> 00243 * To: dev@subversion.tigris.org 00244 * Date: Wed, 12 Dec 2001 09:48:42 -0500 00245 * Message-ID: <87k7vsebp1.fsf@vger.pretzelnet.org> 00246 * Subject: Re: Customizable Keywords</pre> 00247 * 00248 * However, it is considerably more complex than the scheme below. 00249 * For now we're going with simplicity, hopefully the more general 00250 * solution can be done post-1.0. 00251 * 00252 * @defgroup svn_types_keywords keywords 00253 * @{ 00254 */ 00255 00256 /** The maximum size of an expanded or un-expanded keyword. */ 00257 #define SVN_KEYWORD_MAX_LEN 255 00258 00259 /** The most recent revision in which this file was changed. */ 00260 #define SVN_KEYWORD_REVISION_LONG "LastChangedRevision" 00261 00262 /** Short version of LastChangedRevision */ 00263 #define SVN_KEYWORD_REVISION_SHORT "Rev" 00264 00265 /** Medium version of LastChangedRevision, matching the one CVS uses */ 00266 #define SVN_KEYWORD_REVISION_MEDIUM "Revision" 00267 00268 /** The most recent date (repository time) when this file was changed. */ 00269 #define SVN_KEYWORD_DATE_LONG "LastChangedDate" 00270 00271 /** Short version of LastChangedDate */ 00272 #define SVN_KEYWORD_DATE_SHORT "Date" 00273 00274 /** Who most recently committed to this file. */ 00275 #define SVN_KEYWORD_AUTHOR_LONG "LastChangedBy" 00276 00277 /** Short version of LastChangedBy */ 00278 #define SVN_KEYWORD_AUTHOR_SHORT "Author" 00279 00280 /** The URL for the head revision of this file. */ 00281 #define SVN_KEYWORD_URL_LONG "HeadURL" 00282 00283 /** Short version of HeadURL */ 00284 #define SVN_KEYWORD_URL_SHORT "URL" 00285 00286 /** A compressed combination of the other four keywords. */ 00287 #define SVN_KEYWORD_ID "Id" 00288 00289 /** @} */ 00290 00291 00292 /** A structure to represent a path that changed for a log entry. */ 00293 typedef struct svn_log_changed_path_t 00294 { 00295 /** 'A'dd, 'D'elete, 'R'eplace, 'M'odify */ 00296 char action; 00297 00298 /** Source path of copy (if any). */ 00299 const char *copyfrom_path; 00300 00301 /** Source revision of copy (if any). */ 00302 svn_revnum_t copyfrom_rev; 00303 00304 } svn_log_changed_path_t; 00305 00306 00307 /** The callback invoked by log message loopers, such as 00308 * @c svn_ra_plugin_t.get_log() and @c svn_repos_get_logs(). 00309 * 00310 * This function is invoked once on each log message, in the order 00311 * determined by the caller (see above-mentioned functions). 00312 * 00313 * @a baton, @a revision, @a author, @a date, and @a message are what you 00314 * think they are. Any of @a author, @a date, or @a message may be @c NULL. 00315 * 00316 * If @a date is neither null nor the empty string, it was generated by 00317 * @c svn_time_to_string() and can be converted to @c apr_time_t with 00318 * @c svn_time_from_string(). 00319 * 00320 * If @a changed_paths is non-@c NULL, then it contains as keys every path 00321 * committed in @a revision; the values are (@c svn_log_changed_path_t *) 00322 * structures. 00323 * 00324 * ### The only reason @a changed_paths is not qualified with `const' is 00325 * that we usually want to loop over it, and @c apr_hash_first() doesn't 00326 * take a const hash, for various reasons. I'm not sure that those 00327 * "various reasons" are actually even relevant anymore, and if 00328 * they're not, it might be nice to change @c apr_hash_first() so 00329 * read-only uses of hashes can be protected via the type system. 00330 * 00331 * Use @a pool for all allocation. (If the caller is iterating over log 00332 * messages, invoking this receiver on each, we recommend the standard 00333 * pool loop recipe: create a subpool, pass it as @a pool to each call, 00334 * clear it after each iteration, destroy it after the loop is done.) 00335 */ 00336 typedef svn_error_t *(*svn_log_message_receiver_t) 00337 (void *baton, 00338 apr_hash_t *changed_paths, 00339 svn_revnum_t revision, 00340 const char *author, 00341 const char *date, /* use svn_time_from_string() if need apr_time_t */ 00342 const char *message, 00343 apr_pool_t *pool); 00344 00345 00346 /** Callback function type for commits. 00347 * 00348 * When a commit succeeds, an instance of this is invoked on the @a 00349 * new_revision, @a date, and @a author of the commit, along with the 00350 * @a baton closure. 00351 */ 00352 typedef svn_error_t * (*svn_commit_callback_t) ( 00353 svn_revnum_t new_revision, 00354 const char *date, 00355 const char *author, 00356 void *baton); 00357 00358 00359 /** The maximum amount we (ideally) hold in memory at a time when 00360 * processing a stream of data. 00361 * 00362 * For example, when copying data from one stream to another, do it in 00363 * blocks of this size. 00364 */ 00365 #define SVN_STREAM_CHUNK_SIZE 102400 00366 00367 /** The maximum amount we can ever hold in memory. */ 00368 /* FIXME: Should this be the same as SVN_STREAM_CHUNK_SIZE? */ 00369 #define SVN_MAX_OBJECT_SIZE (((apr_size_t) -1) / 2) 00370 00371 00372 00373 /* ### Note: despite being about mime-TYPES, these probably don't 00374 * ### belong in svn_types.h. However, no other header is more 00375 * ### appropriate, and didn't feel like creating svn_validate.h for 00376 * ### so little. 00377 */ 00378 00379 /** Validate @a mime_type. 00380 * 00381 * If @a mime_type does not contain a "/", or ends with non-alphanumeric 00382 * data, return @c SVN_ERR_BAD_MIME_TYPE, else return success. 00383 * 00384 * Use @a pool only to find error allocation. 00385 * 00386 * Goal: to match both "foo/bar" and "foo/bar; charset=blah", without 00387 * being too strict about it, but to disallow mime types that have 00388 * quotes, newlines, or other garbage on the end, such as might be 00389 * unsafe in an HTTP header. 00390 */ 00391 svn_error_t *svn_mime_type_validate (const char *mime_type, 00392 apr_pool_t *pool); 00393 00394 00395 /** Return false iff @a mime_type is a textual type. 00396 * 00397 * All mime types that start with "text/" are textual, plus some special 00398 * cases (for example, "image/x-xbitmap"). 00399 */ 00400 svn_boolean_t svn_mime_type_is_binary (const char *mime_type); 00401 00402 00403 00404 /** A user defined callback that subversion will call with a user defined 00405 * baton to see if the current operation should be continued. If the operation 00406 * should continue, the function should return @c SVN_NO_ERROR, if not, it 00407 * should return @c SVN_ERR_CANCELLED. 00408 */ 00409 typedef svn_error_t *(*svn_cancel_func_t) (void *cancel_baton); 00410 00411 00412 00413 /** @since New in 1.2 00414 * 00415 * A lock object, for client & server to share. 00416 * 00417 * A lock represents the exclusive right to add, delete, or modify a 00418 * path. A lock is created in a repository, wholly controlled by the 00419 * repository. A "lock-token" is the lock's UUID, and can be used to 00420 * learn more about a lock's fields, and or/make use of the lock. 00421 * Because a lock is immutable, a client is free to not only cache the 00422 * lock-token, but the lock's fields too, for convenience. 00423 * 00424 * Note that the 'is_dav_comment' field is wholly ignored by every 00425 * library except for mod_dav_svn. The field isn't even marshalled 00426 * over the network to the client. Assuming lock structures are 00427 * created with apr_pcalloc(), a default value of 0 is universally safe. 00428 * 00429 * @note in the current implementation, only files are lockable. 00430 */ 00431 typedef struct svn_lock_t 00432 { 00433 const char *path; /**< the path this lock applies to */ 00434 const char *token; /**< unique URI representing lock */ 00435 const char *owner; /**< the username which owns the lock */ 00436 const char *comment; /**< (optional) description of lock */ 00437 svn_boolean_t is_dav_comment; /**< was comment made by generic DAV client? */ 00438 apr_time_t creation_date; /**< when lock was made */ 00439 apr_time_t expiration_date; /**< (optional) when lock will expire; 00440 If value is 0, lock will never expire. */ 00441 } svn_lock_t; 00442 00443 /** @since New in 1.2. 00444 * 00445 * Returns an @c svn_lock_t, allocated in @a pool with all fields initialized 00446 * to null values. 00447 * 00448 * @note To allow for extending the @c svn_lock_t structure in the future 00449 * releases, this function should always be used to allocate the structure. 00450 */ 00451 svn_lock_t * 00452 svn_lock_create (apr_pool_t *pool); 00453 00454 /** @since New in 1.2. 00455 * 00456 * Return a deep copy of @a lock, allocated in @a pool. 00457 */ 00458 svn_lock_t * 00459 svn_lock_dup (const svn_lock_t *lock, apr_pool_t *pool); 00460 00461 #ifdef __cplusplus 00462 } 00463 #endif /* __cplusplus */ 00464 00465 #endif /* SVN_TYPES_H */