svn_props.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_props.h
00019  * @brief Subversion properties
00020  */
00021 
00022 /* ==================================================================== */
00023 
00024 #ifndef SVN_PROPS_H
00025 #define SVN_PROPS_H
00026 
00027 #include <apr_pools.h>
00028 #include <apr_tables.h>
00029 
00030 #include "svn_string.h"
00031 
00032 #ifdef __cplusplus
00033 extern "C" {
00034 #endif /* __cplusplus */
00035 
00036 
00037 
00038 
00039 /** A general in-memory representation of a single property.  Most of
00040  * the time, property lists will be stored completely in hashes.  But
00041  * sometimes it's useful to have an "ordered" collection of
00042  * properties, in which case we use an array of these structures.
00043  *
00044  * Also: sometimes we want a list that represents a set of property
00045  * *changes*, and in this case, an @c apr_hash_t won't work -- there's no
00046  * way to represent a property deletion, because we can't store a @c NULL
00047  * value in a hash.  So instead, we use these structures.
00048  */
00049 typedef struct svn_prop_t
00050 {
00051   const char *name;           /**< Property name */
00052   const svn_string_t *value;  /**< Property value */
00053 } svn_prop_t;
00054 
00055 
00056 /**
00057  * Return a duplicate of @a prop, allocated in @a pool. No part of the new
00058  * structure will be shared with @a prop.
00059  *
00060  * @since New in 1.3.
00061  */
00062 svn_prop_t *svn_prop_dup(const svn_prop_t *prop, apr_pool_t *pool);
00063 
00064 
00065 /**
00066  * Duplicate an @a array of svn_prop_t items using @a pool.
00067  *
00068  * @since New in 1.3.
00069  */
00070 apr_array_header_t *
00071 svn_prop_array_dup(const apr_array_header_t *array, apr_pool_t *pool);
00072 
00073 
00074 /**
00075  * Subversion distinguishes among several kinds of properties,
00076  * particularly on the client-side.  There is no "unknown" kind; if
00077  * there's nothing special about a property name, the default category
00078  * is @c svn_prop_regular_kind.
00079  */ 
00080 typedef enum svn_prop_kind
00081 {
00082   /** In .svn/entries, i.e., author, date, etc. */
00083   svn_prop_entry_kind,
00084 
00085   /** Client-side only, stored by specific RA layer. */
00086   svn_prop_wc_kind,
00087 
00088   /** Seen if user does "svn proplist"; note that this includes some "svn:" 
00089    * props and all user props, i.e. ones stored in the repository fs.
00090    */
00091   svn_prop_regular_kind 
00092 } svn_prop_kind_t;
00093 
00094 /** Return the prop kind of a property named @a name, and (if @a prefix_len
00095  * is non-@c NULL) set @a *prefix_len to the length of the prefix of @a name
00096  * that was sufficient to distinguish its kind.
00097  */
00098 svn_prop_kind_t svn_property_kind(int *prefix_len,
00099                                   const char *prop_name);
00100 
00101 
00102 /** Return @c TRUE iff @a prop_name represents the name of a Subversion
00103  * property.
00104  */
00105 svn_boolean_t svn_prop_is_svn_prop(const char *prop_name);
00106 
00107 
00108 /** If @a propname requires that its value be stored as UTF8/LF in the
00109  * repository, then return @c TRUE.  Else return @c FALSE.  This is for
00110  * users of libsvn_client or libsvn_fs, since it their responsibility
00111  * to do this translation in both directions.  (See
00112  * svn_subst_translate_string()/svn_subst_detranslate_string() for
00113  * help with this task.)
00114  */
00115 svn_boolean_t svn_prop_needs_translation(const char *propname);
00116 
00117 
00118 /** Given a @a proplist array of @c svn_prop_t structures, allocate
00119  * three new arrays in @a pool.  Categorize each property and then
00120  * create new @c svn_prop_t structures in the proper lists.  Each new
00121  * @c svn_prop_t structure's fields will point to the same data within
00122  * @a proplist's structures.
00123  *
00124  * Callers may pass NULL for each of the property lists in which they
00125  * are uninterested.  If no props exist in a certain category, and the
00126  * property list argument for that category is non-NULL, then that
00127  * array will come back with <tt>->nelts == 0</tt>.
00128  *
00129  * ### Hmmm, maybe a better future interface is to return an array of
00130  *     arrays, where the index into the array represents the index
00131  *     into @c svn_prop_kind_t.  That way we can add more prop kinds
00132  *     in the future without changing this interface... 
00133  */
00134 svn_error_t *svn_categorize_props(const apr_array_header_t *proplist,
00135                                   apr_array_header_t **entry_props,
00136                                   apr_array_header_t **wc_props,
00137                                   apr_array_header_t **regular_props,
00138                                   apr_pool_t *pool);
00139 
00140 
00141 /** Given two property hashes (<tt>const char *name</tt> -> <tt>const 
00142  * svn_string_t *value</tt>), deduce the differences between them (from 
00143  * @a source_props -> @c target_props).  Return these changes as a series of 
00144  * @c svn_prop_t structures stored in @a propdiffs, allocated from @a pool.
00145  *
00146  * For note, here's a quick little table describing the logic of this
00147  * routine:
00148  *
00149  *<pre> basehash        localhash         event
00150  * --------        ---------         -----
00151  * value = foo     value = NULL      Deletion occurred.
00152  * value = foo     value = bar       Set occurred (modification)
00153  * value = NULL    value = baz       Set occurred (creation)</pre>
00154  */
00155 svn_error_t *svn_prop_diffs(apr_array_header_t **propdiffs,
00156                             apr_hash_t *target_props,
00157                             apr_hash_t *source_props,
00158                             apr_pool_t *pool);
00159 
00160 
00161 
00162 /* Defines for reserved ("svn:") property names.  */
00163 
00164 /** All Subversion property names start with this. */
00165 #define SVN_PROP_PREFIX "svn:"
00166 
00167 
00168 /** Visible properties
00169  *
00170  * These are regular properties that are attached to ordinary files
00171  * and dirs, and are visible (and tweakable) by svn client programs
00172  * and users.  Adding these properties causes specific effects.
00173  *
00174  * @note the values of these properties are always UTF8-encoded with
00175  * LF line-endings.  It is the burden of svn library users to enforce
00176  * this.  Use svn_prop_needs_translation() to discover if a
00177  * certain property needs translation, and you can use
00178  * svn_subst_translate_string()/svn_subst_detranslate_string() 
00179  * to do the translation.
00180  *
00181  * @defgroup svn_prop_visible_props Visible properties
00182  * @{
00183  */
00184 
00185 /** The mime-type of a given file. */
00186 #define SVN_PROP_MIME_TYPE  SVN_PROP_PREFIX "mime-type"
00187 
00188 /** The ignore patterns for a given directory. */
00189 #define SVN_PROP_IGNORE  SVN_PROP_PREFIX "ignore"
00190 
00191 /** The line ending style for a given file. */
00192 #define SVN_PROP_EOL_STYLE  SVN_PROP_PREFIX "eol-style"
00193 
00194 /** The "activated" keywords (for keyword substitution) for a given file. */
00195 #define SVN_PROP_KEYWORDS  SVN_PROP_PREFIX "keywords"
00196 
00197 /** Set to either TRUE or FALSE if we want a file to be executable or not. */
00198 #define SVN_PROP_EXECUTABLE  SVN_PROP_PREFIX "executable"
00199 
00200 /** The value to force the executable property to when set */
00201 #define SVN_PROP_EXECUTABLE_VALUE "*"
00202 
00203 /** Set to TRUE ('*') if we want a file to be set to read-only when
00204  * not locked.  FALSE is indicated by deleting the property. */
00205 #define SVN_PROP_NEEDS_LOCK  SVN_PROP_PREFIX "needs-lock"
00206 
00207 /** The value to force the needs-lock property to when set */
00208 #define SVN_PROP_NEEDS_LOCK_VALUE "*"
00209 
00210 /** Set if the file should be treated as a special file. */
00211 #define SVN_PROP_SPECIAL  SVN_PROP_PREFIX "special"
00212 
00213 /** The value to force the special property to when set. */
00214 #define SVN_PROP_SPECIAL_VALUE "*"
00215 
00216 /** Describes external items to check out into this directory. 
00217  *
00218  * The format is a series of lines, such as:
00219  *
00220  *<pre>   localdir1           http://url.for.external.source/etc/
00221  *   localdir1/foo       http://url.for.external.source/foo
00222  *   localdir1/bar       http://blah.blah.blah/repositories/theirproj
00223  *   localdir1/bar/baz   http://blorg.blorg.blorg/basement/code
00224  *   localdir2           http://another.url/blah/blah/blah
00225  *   localdir3           http://and.so.on/and/so/forth</pre>
00226  *
00227  * The subdir names on the left side are relative to the directory on
00228  * which this property is set.
00229  */
00230 #define SVN_PROP_EXTERNALS  SVN_PROP_PREFIX "externals"
00231 
00232 /** @} */
00233 
00234 /** WC props are props that are invisible to users:  they're generated
00235  * by an RA layer, and stored in secret parts of .svn/.
00236  *
00237  * @defgroup svn_prop_invisible_props Invisible properties
00238  * @{
00239  */
00240 
00241 /** The propname *prefix* that makes a propname a "WC property". 
00242  *
00243  * For example, ra_dav might store a versioned-resource url as a WC
00244  * prop like this:
00245  *
00246  *<pre>    name = svn:wc:dav_url
00247  *    val  = http://www.lyra.org/repos/452348/e.289</pre>
00248  *
00249  * The client will try to protect WC props by warning users against
00250  * changing them.  The client will also send them back to the RA layer
00251  * when committing.
00252  */
00253 #define SVN_PROP_WC_PREFIX     SVN_PROP_PREFIX "wc:"
00254 
00255 /** Another type of non-user-visible property.  "Entry properties" are
00256  * stored as fields with the administrative 'entries' file.  
00257  */
00258 #define SVN_PROP_ENTRY_PREFIX  SVN_PROP_PREFIX "entry:"
00259 
00260 /** The revision this entry was last committed to on. */
00261 #define SVN_PROP_ENTRY_COMMITTED_REV     SVN_PROP_ENTRY_PREFIX "committed-rev"
00262 
00263 /** The date this entry was last committed to on. */
00264 #define SVN_PROP_ENTRY_COMMITTED_DATE    SVN_PROP_ENTRY_PREFIX "committed-date"
00265 
00266 /** The author who last committed to this entry. */
00267 #define SVN_PROP_ENTRY_LAST_AUTHOR       SVN_PROP_ENTRY_PREFIX "last-author"
00268 
00269 /** The UUID of this entry's repository. */
00270 #define SVN_PROP_ENTRY_UUID       SVN_PROP_ENTRY_PREFIX "uuid"
00271 
00272 /** The lock token for this entry.
00273  * @since New in 1.2. */
00274 #define SVN_PROP_ENTRY_LOCK_TOKEN SVN_PROP_ENTRY_PREFIX "lock-token"
00275 
00276 /** When custom, user-defined properties are passed over the wire, they will
00277  * have this prefix added to their name.
00278  */
00279 #define SVN_PROP_CUSTOM_PREFIX SVN_PROP_PREFIX "custom:"
00280 
00281 /** @} */
00282 
00283 /**
00284  * These are reserved properties attached to a "revision" object in
00285  * the repository filesystem.  They can be queried by using
00286  * svn_fs_revision_prop().  They are invisible to svn clients.
00287  *
00288  * @defgroup svn_props_revision_props Revision properties
00289  * @{
00290  */
00291 
00292 /** The fs revision property that stores a commit's author. */
00293 #define SVN_PROP_REVISION_AUTHOR  SVN_PROP_PREFIX "author"
00294 
00295 /** The fs revision property that stores a commit's log message. */
00296 #define SVN_PROP_REVISION_LOG  SVN_PROP_PREFIX "log"
00297 
00298 /** The fs revision property that stores a commit's date. */
00299 #define SVN_PROP_REVISION_DATE  SVN_PROP_PREFIX "date"
00300 
00301 /** The fs revision property that stores a commit's "original" date.
00302  *
00303  * The svn:date property must be monotonically increasing, along with
00304  * the revision number. In certain scenarios, this may pose a problem
00305  * when the revision represents a commit that occurred at a time which
00306  * does not fit within the sequencing required for svn:date. This can
00307  * happen, for instance, when the revision represents a commit to a
00308  * foreign version control system, or possibly when two Subversion
00309  * repositories are combined. This property can be used to record the
00310  * true, original date of the commit.
00311  */
00312 #define SVN_PROP_REVISION_ORIG_DATE  SVN_PROP_PREFIX "original-date"
00313 
00314 /** The presence of this fs revision property indicates that the
00315  * revision was automatically generated by the mod_dav_svn
00316  * autoversioning feature.  The value is irrelevant.
00317  */
00318 #define SVN_PROP_REVISION_AUTOVERSIONED  SVN_PROP_PREFIX "autoversioned"
00319 
00320 
00321 /* More reserved revision props in the 'svn:' namespace, used by the
00322    svnsync tool:   */
00323 
00324 /** Prefix for all svnsync custom properties. */
00325 #define SVNSYNC_PROP_PREFIX             SVN_PROP_PREFIX "sync-"
00326 
00327 /* The following revision properties are set on revision 0 of
00328  * destination repositories by svnsync:
00329  */
00330 
00331 /** Used to enforce mutually exclusive destination repository access. */
00332 #define SVNSYNC_PROP_LOCK               SVNSYNC_PROP_PREFIX "lock"
00333 
00334 /** Identifies the repository's source URL. */
00335 #define SVNSYNC_PROP_FROM_URL           SVNSYNC_PROP_PREFIX "from-url"
00336 /** Identifies the repository's source UUID. */
00337 #define SVNSYNC_PROP_FROM_UUID          SVNSYNC_PROP_PREFIX "from-uuid"
00338 
00339 /** Identifies the last completely mirrored revision. */
00340 #define SVNSYNC_PROP_LAST_MERGED_REV    SVNSYNC_PROP_PREFIX "last-merged-rev"
00341 
00342 /** Identifies the revision currently being copied. */
00343 #define SVNSYNC_PROP_CURRENTLY_COPYING  SVNSYNC_PROP_PREFIX "currently-copying"
00344 
00345 
00346 /**
00347  * This is a list of all revision properties.
00348  */ 
00349 #define SVN_PROP_REVISION_ALL_PROPS SVN_PROP_REVISION_AUTHOR, \
00350                                     SVN_PROP_REVISION_LOG, \
00351                                     SVN_PROP_REVISION_DATE, \
00352                                     SVN_PROP_REVISION_AUTOVERSIONED, \
00353                                     SVN_PROP_REVISION_ORIG_DATE, \
00354                                     SVNSYNC_PROP_LOCK, \
00355                                     SVNSYNC_PROP_FROM_URL, \
00356                                     SVNSYNC_PROP_FROM_UUID, \
00357                                     SVNSYNC_PROP_LAST_MERGED_REV, \
00358                                     SVNSYNC_PROP_CURRENTLY_COPYING,
00359 
00360 /** @} */
00361 
00362 
00363 
00364 #ifdef __cplusplus
00365 }
00366 #endif /* __cplusplus */
00367 
00368 #endif /* SVN_PROPS_H */

Generated on Mon Oct 15 09:23:50 2007 for Subversion by  doxygen 1.5.1