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 */