include/subversion-1/svn_props.h

   1 /**
   2  * @copyright
   3  * ====================================================================
   4  * Copyright (c) 2000-2004 CollabNet.  All rights reserved.
   5  *
   6  * This software is licensed as described in the file COPYING, which
   7  * you should have received as part of this distribution.  The terms
   8  * are also available at http://subversion.tigris.org/license-1.html.
   9  * If newer versions of this license are posted there, you may use a
  10  * newer version instead, at your option.
  11  *
  12  * This software consists of voluntary contributions made by many
  13  * individuals.  For exact contribution history, see the revision
  14  * history and logs, available at http://subversion.tigris.org/.
  15  * ====================================================================
  16  * @endcopyright
  17  *
  18  * @file svn_props.h
  19  * @brief Subversion properties
  20  */
  21
  22 /* ==================================================================== */
  23
  24 #ifndef SVN_PROPS_H
  25 #define SVN_PROPS_H
  26
  27 #include <apr_pools.h>
  28 #include <apr_tables.h>
  29
  30 #include "svn_string.h"
  31
  32 #ifdef __cplusplus
  33 extern "C" {
  34 #endif /* __cplusplus */
  35
  36
  37 \f
  38
  39 /** A general in-memory representation of a single property.  Most of
  40  * the time, property lists will be stored completely in hashes.  But
  41  * sometimes it's useful to have an "ordered" collection of
  42  * properties, in which case we use an array of these structures.
  43  *
  44  * Also: sometimes we want a list that represents a set of property
  45  * *changes*, and in this case, an @c apr_hash_t won't work -- there's no
  46  * way to represent a property deletion, because we can't store a @c NULL
  47  * value in a hash.  So instead, we use these structures.
  48  */
  49 typedef struct svn_prop_t
  50 {
  51   const char *name;           /**< Property name */
  52   const svn_string_t *value;  /**< Property value */
  53 } svn_prop_t;
  54
  55
  56 /**
  57  * Return a duplicate of @a prop, allocated in @a pool. No part of the new
  58  * structure will be shared with @a prop.
  59  *
  60  * @since New in 1.3.
  61  */
  62 svn_prop_t *svn_prop_dup(const svn_prop_t *prop, apr_pool_t *pool);
  63
  64
  65 /**
  66  * Duplicate an @a array of svn_prop_t items using @a pool.
  67  *
  68  * @since New in 1.3.
  69  */
  70 apr_array_header_t *
  71 svn_prop_array_dup(const apr_array_header_t *array, apr_pool_t *pool);
  72
  73
  74 /**
  75  * Subversion distinguishes among several kinds of properties,
  76  * particularly on the client-side.  There is no "unknown" kind; if
  77  * there's nothing special about a property name, the default category
  78  * is @c svn_prop_regular_kind.
  79  */
  80 typedef enum svn_prop_kind
  81 {
  82   /** In .svn/entries, i.e., author, date, etc. */
  83   svn_prop_entry_kind,
  84
  85   /** Client-side only, stored by specific RA layer. */
  86   svn_prop_wc_kind,
  87
  88   /** Seen if user does "svn proplist"; note that this includes some "svn:"
  89    * props and all user props, i.e. ones stored in the repository fs.
  90    */
  91   svn_prop_regular_kind
  92 } svn_prop_kind_t;
  93
  94 /** Return the prop kind of a property named @a name, and (if @a prefix_len
  95  * is non-@c NULL) set @a *prefix_len to the length of the prefix of @a name
  96  * that was sufficient to distinguish its kind.
  97  */
  98 svn_prop_kind_t svn_property_kind(int *prefix_len,
  99                                   const char *prop_name);
 100
 101
 102 /** Return @c TRUE iff @a prop_name represents the name of a Subversion
 103  * property.
 104  */
 105 svn_boolean_t svn_prop_is_svn_prop(const char *prop_name);
 106
 107
 108 /** If @a propname requires that its value be stored as UTF8/LF in the
 109  * repository, then return @c TRUE.  Else return @c FALSE.  This is for
 110  * users of libsvn_client or libsvn_fs, since it their responsibility
 111  * to do this translation in both directions.  (See
 112  * svn_subst_translate_string()/svn_subst_detranslate_string() for
 113  * help with this task.)
 114  */
 115 svn_boolean_t svn_prop_needs_translation(const char *propname);
 116
 117
 118 /** Given a @a proplist array of @c svn_prop_t structures, allocate
 119  * three new arrays in @a pool.  Categorize each property and then
 120  * create new @c svn_prop_t structures in the proper lists.  Each new
 121  * @c svn_prop_t structure's fields will point to the same data within
 122  * @a proplist's structures.
 123  *
 124  * Callers may pass NULL for each of the property lists in which they
 125  * are uninterested.  If no props exist in a certain category, and the
 126  * property list argument for that category is non-NULL, then that
 127  * array will come back with <tt>->nelts == 0</tt>.
 128  *
 129  * ### Hmmm, maybe a better future interface is to return an array of
 130  *     arrays, where the index into the array represents the index
 131  *     into @c svn_prop_kind_t.  That way we can add more prop kinds
 132  *     in the future without changing this interface...
 133  */
 134 svn_error_t *svn_categorize_props(const apr_array_header_t *proplist,
 135                                   apr_array_header_t **entry_props,
 136                                   apr_array_header_t **wc_props,
 137                                   apr_array_header_t **regular_props,
 138                                   apr_pool_t *pool);
 139
 140
 141 /** Given two property hashes (<tt>const char *name</tt> -> <tt>const
 142  * svn_string_t *value</tt>), deduce the differences between them (from
 143  * @a source_props -> @c target_props).  Return these changes as a series of
 144  * @c svn_prop_t structures stored in @a propdiffs, allocated from @a pool.
 145  *
 146  * For note, here's a quick little table describing the logic of this
 147  * routine:
 148  *
 149  *<pre> basehash        localhash         event
 150  * --------        ---------         -----
 151  * value = foo     value = NULL      Deletion occurred.
 152  * value = foo     value = bar       Set occurred (modification)
 153  * value = NULL    value = baz       Set occurred (creation)</pre>
 154  */
 155 svn_error_t *svn_prop_diffs(apr_array_header_t **propdiffs,
 156                             apr_hash_t *target_props,
 157                             apr_hash_t *source_props,
 158                             apr_pool_t *pool);
 159
 160
 161 \f
 162 /* Defines for reserved ("svn:") property names.  */
 163
 164 /** All Subversion property names start with this. */
 165 #define SVN_PROP_PREFIX "svn:"
 166
 167
 168 /** Visible properties
 169  *
 170  * These are regular properties that are attached to ordinary files
 171  * and dirs, and are visible (and tweakable) by svn client programs
 172  * and users.  Adding these properties causes specific effects.
 173  *
 174  * @note the values of these properties are always UTF8-encoded with
 175  * LF line-endings.  It is the burden of svn library users to enforce
 176  * this.  Use svn_prop_needs_translation() to discover if a
 177  * certain property needs translation, and you can use
 178  * svn_subst_translate_string()/svn_subst_detranslate_string()
 179  * to do the translation.
 180  *
 181  * @defgroup svn_prop_visible_props Visible properties
 182  * @{
 183  */
 184
 185 /** The mime-type of a given file. */
 186 #define SVN_PROP_MIME_TYPE  SVN_PROP_PREFIX "mime-type"
 187
 188 /** The ignore patterns for a given directory. */
 189 #define SVN_PROP_IGNORE  SVN_PROP_PREFIX "ignore"
 190
 191 /** The line ending style for a given file. */
 192 #define SVN_PROP_EOL_STYLE  SVN_PROP_PREFIX "eol-style"
 193
 194 /** The "activated" keywords (for keyword substitution) for a given file. */
 195 #define SVN_PROP_KEYWORDS  SVN_PROP_PREFIX "keywords"
 196
 197 /** Set to either TRUE or FALSE if we want a file to be executable or not. */
 198 #define SVN_PROP_EXECUTABLE  SVN_PROP_PREFIX "executable"
 199
 200 /** The value to force the executable property to when set */
 201 #define SVN_PROP_EXECUTABLE_VALUE "*"
 202
 203 /** Set to TRUE ('*') if we want a file to be set to read-only when
 204  * not locked.  FALSE is indicated by deleting the property. */
 205 #define SVN_PROP_NEEDS_LOCK  SVN_PROP_PREFIX "needs-lock"
 206
 207 /** The value to force the needs-lock property to when set */
 208 #define SVN_PROP_NEEDS_LOCK_VALUE "*"
 209
 210 /** Set if the file should be treated as a special file. */
 211 #define SVN_PROP_SPECIAL  SVN_PROP_PREFIX "special"
 212
 213 /** The value to force the special property to when set. */
 214 #define SVN_PROP_SPECIAL_VALUE "*"
 215
 216 /** Describes external items to check out into this directory.
 217  *
 218  * The format is a series of lines, such as:
 219  *
 220  *<pre>   localdir1           http://url.for.external.source/etc/
 221  *   localdir1/foo       http://url.for.external.source/foo
 222  *   localdir1/bar       http://blah.blah.blah/repositories/theirproj
 223  *   localdir1/bar/baz   http://blorg.blorg.blorg/basement/code
 224  *   localdir2           http://another.url/blah/blah/blah
 225  *   localdir3           http://and.so.on/and/so/forth</pre>
 226  *
 227  * The subdir names on the left side are relative to the directory on
 228  * which this property is set.
 229  */
 230 #define SVN_PROP_EXTERNALS  SVN_PROP_PREFIX "externals"
 231
 232 /** @} */
 233
 234 /** WC props are props that are invisible to users:  they're generated
 235  * by an RA layer, and stored in secret parts of .svn/.
 236  *
 237  * @defgroup svn_prop_invisible_props Invisible properties
 238  * @{
 239  */
 240
 241 /** The propname *prefix* that makes a propname a "WC property".
 242  *
 243  * For example, ra_dav might store a versioned-resource url as a WC
 244  * prop like this:
 245  *
 246  *<pre>    name = svn:wc:dav_url
 247  *    val  = http://www.lyra.org/repos/452348/e.289</pre>
 248  *
 249  * The client will try to protect WC props by warning users against
 250  * changing them.  The client will also send them back to the RA layer
 251  * when committing.
 252  */
 253 #define SVN_PROP_WC_PREFIX     SVN_PROP_PREFIX "wc:"
 254
 255 /** Another type of non-user-visible property.  "Entry properties" are
 256  * stored as fields with the administrative 'entries' file.
 257  */
 258 #define SVN_PROP_ENTRY_PREFIX  SVN_PROP_PREFIX "entry:"
 259
 260 /** The revision this entry was last committed to on. */
 261 #define SVN_PROP_ENTRY_COMMITTED_REV     SVN_PROP_ENTRY_PREFIX "committed-rev"
 262
 263 /** The date this entry was last committed to on. */
 264 #define SVN_PROP_ENTRY_COMMITTED_DATE    SVN_PROP_ENTRY_PREFIX "committed-date"
 265
 266 /** The author who last committed to this entry. */
 267 #define SVN_PROP_ENTRY_LAST_AUTHOR       SVN_PROP_ENTRY_PREFIX "last-author"
 268
 269 /** The UUID of this entry's repository. */
 270 #define SVN_PROP_ENTRY_UUID       SVN_PROP_ENTRY_PREFIX "uuid"
 271
 272 /** The lock token for this entry.
 273  * @since New in 1.2. */
 274 #define SVN_PROP_ENTRY_LOCK_TOKEN SVN_PROP_ENTRY_PREFIX "lock-token"
 275
 276 /** When custom, user-defined properties are passed over the wire, they will
 277  * have this prefix added to their name.
 278  */
 279 #define SVN_PROP_CUSTOM_PREFIX SVN_PROP_PREFIX "custom:"
 280
 281 /** @} */
 282
 283 /**
 284  * These are reserved properties attached to a "revision" object in
 285  * the repository filesystem.  They can be queried by using
 286  * svn_fs_revision_prop().  They are invisible to svn clients.
 287  *
 288  * @defgroup svn_props_revision_props Revision properties
 289  * @{
 290  */
 291
 292 /** The fs revision property that stores a commit's author. */
 293 #define SVN_PROP_REVISION_AUTHOR  SVN_PROP_PREFIX "author"
 294
 295 /** The fs revision property that stores a commit's log message. */
 296 #define SVN_PROP_REVISION_LOG  SVN_PROP_PREFIX "log"
 297
 298 /** The fs revision property that stores a commit's date. */
 299 #define SVN_PROP_REVISION_DATE  SVN_PROP_PREFIX "date"
 300
 301 /** The fs revision property that stores a commit's "original" date.
 302  *
 303  * The svn:date property must be monotonically increasing, along with
 304  * the revision number. In certain scenarios, this may pose a problem
 305  * when the revision represents a commit that occurred at a time which
 306  * does not fit within the sequencing required for svn:date. This can
 307  * happen, for instance, when the revision represents a commit to a
 308  * foreign version control system, or possibly when two Subversion
 309  * repositories are combined. This property can be used to record the
 310  * true, original date of the commit.
 311  */
 312 #define SVN_PROP_REVISION_ORIG_DATE  SVN_PROP_PREFIX "original-date"
 313
 314 /** The presence of this fs revision property indicates that the
 315  * revision was automatically generated by the mod_dav_svn
 316  * autoversioning feature.  The value is irrelevant.
 317  */
 318 #define SVN_PROP_REVISION_AUTOVERSIONED  SVN_PROP_PREFIX "autoversioned"
 319
 320
 321 /* More reserved revision props in the 'svn:' namespace, used by the
 322    svnsync tool:   */
 323
 324 /** Prefix for all svnsync custom properties. */
 325 #define SVNSYNC_PROP_PREFIX             SVN_PROP_PREFIX "sync-"
 326
 327 /* The following revision properties are set on revision 0 of
 328  * destination repositories by svnsync:
 329  */
 330
 331 /** Used to enforce mutually exclusive destination repository access. */
 332 #define SVNSYNC_PROP_LOCK               SVNSYNC_PROP_PREFIX "lock"
 333
 334 /** Identifies the repository's source URL. */
 335 #define SVNSYNC_PROP_FROM_URL           SVNSYNC_PROP_PREFIX "from-url"
 336 /** Identifies the repository's source UUID. */
 337 #define SVNSYNC_PROP_FROM_UUID          SVNSYNC_PROP_PREFIX "from-uuid"
 338
 339 /** Identifies the last completely mirrored revision. */
 340 #define SVNSYNC_PROP_LAST_MERGED_REV    SVNSYNC_PROP_PREFIX "last-merged-rev"
 341
 342 /** Identifies the revision currently being copied. */
 343 #define SVNSYNC_PROP_CURRENTLY_COPYING  SVNSYNC_PROP_PREFIX "currently-copying"
 344
 345
 346 /**
 347  * This is a list of all revision properties.
 348  */
 349 #define SVN_PROP_REVISION_ALL_PROPS SVN_PROP_REVISION_AUTHOR, \
 350                                     SVN_PROP_REVISION_LOG, \
 351                                     SVN_PROP_REVISION_DATE, \
 352                                     SVN_PROP_REVISION_AUTOVERSIONED, \
 353                                     SVN_PROP_REVISION_ORIG_DATE, \
 354                                     SVNSYNC_PROP_LOCK, \
 355                                     SVNSYNC_PROP_FROM_URL, \
 356                                     SVNSYNC_PROP_FROM_UUID, \
 357                                     SVNSYNC_PROP_LAST_MERGED_REV, \
 358                                     SVNSYNC_PROP_CURRENTLY_COPYING,
 359
 360 /** @} */
 361
 362 \f
 363
 364 #ifdef __cplusplus
 365 }
 366 #endif /* __cplusplus */
 367
 368 #endif /* SVN_PROPS_H */