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

Generated on Wed Oct 22 14:54:29 2008 for Subversion by  doxygen 1.4.7