Main Page | Modules | Data Structures | File List | Data Fields | Globals | Related Pages

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 /** 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 */

Generated on Thu Aug 25 00:11:40 2005 for Subversion by  doxygen 1.3.9.1