- Main Page
- Related Pages
- Modules
- Data Structures
- Files

- File List
- Globals

# svn_props.h

Go to the documentation of this file.

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

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines