Subversion 1.6.16

svn_props.h

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