svn_types.h

Go to the documentation of this file.
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_cstring() and can be converted to @c apr_time_t with
00428  * svn_time_from_cstring().
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_cstring() 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 */

Generated on Sun Sep 16 17:37:59 2007 for Subversion by  doxygen 1.5.1