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