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 00038 00039 /** A general in-memory representation of a single property. Most of 00040 * the time, property lists will be stored completely in hashes. But 00041 * sometimes it's useful to have an "ordered" collection of 00042 * properties, in which case we use an array of these structures. 00043 * 00044 * Also: sometimes we want a list that represents a set of property 00045 * *changes*, and in this case, an @c apr_hash_t won't work -- there's no 00046 * way to represent a property deletion, because we can't store a @c NULL 00047 * value in a hash. So instead, we use these structures. 00048 */ 00049 typedef struct svn_prop_t 00050 { 00051 const char *name; /**< Property name */ 00052 const svn_string_t *value; /**< Property value */ 00053 } svn_prop_t; 00054 00055 00056 /** 00057 * Return a duplicate of @a prop, allocated in @a pool. No part of the new 00058 * structure will be shared with @a prop. 00059 * 00060 * @since New in 1.3. 00061 */ 00062 svn_prop_t *svn_prop_dup(const svn_prop_t *prop, apr_pool_t *pool); 00063 00064 00065 /** 00066 * Duplicate an @a array of svn_prop_t items using @a pool. 00067 * 00068 * @since New in 1.3. 00069 */ 00070 apr_array_header_t * 00071 svn_prop_array_dup (const apr_array_header_t *array, apr_pool_t *pool); 00072 00073 00074 /** 00075 * Subversion distinguishes among several kinds of properties, 00076 * particularly on the client-side. There is no "unknown" kind; if 00077 * there's nothing special about a property name, the default category 00078 * is @c svn_prop_regular_kind. 00079 */ 00080 typedef enum svn_prop_kind 00081 { 00082 /** In .svn/entries, i.e., author, date, etc. */ 00083 svn_prop_entry_kind, 00084 00085 /** Client-side only, stored by specific RA layer. */ 00086 svn_prop_wc_kind, 00087 00088 /** Seen if user does "svn proplist"; note that this includes some "svn:" 00089 * props and all user props, i.e. ones stored in the repository fs. 00090 */ 00091 svn_prop_regular_kind 00092 } svn_prop_kind_t; 00093 00094 /** Return the prop kind of a property named @a name, and (if @a prefix_len 00095 * is non-@c NULL) set @a *prefix_len to the length of the prefix of @a name 00096 * that was sufficient to distinguish its kind. 00097 */ 00098 svn_prop_kind_t svn_property_kind (int *prefix_len, 00099 const char *prop_name); 00100 00101 00102 /** Return @c TRUE iff @a prop_name represents the name of a Subversion 00103 * property. 00104 */ 00105 svn_boolean_t svn_prop_is_svn_prop (const char *prop_name); 00106 00107 00108 /** If @a propname requires that its value be stored as UTF8/LF in the 00109 * repository, then return @c TRUE. Else return @c FALSE. This is for 00110 * users of libsvn_client or libsvn_fs, since it their responsibility 00111 * to do this translation in both directions. (See 00112 * svn_subst_translate_string()/svn_subst_detranslate_string() for 00113 * help with this task.) 00114 */ 00115 svn_boolean_t svn_prop_needs_translation (const char *propname); 00116 00117 00118 /** Given a @a proplist array of @c svn_prop_t structures, allocate 00119 * three new arrays in @a pool. Categorize each property and then 00120 * create new @c svn_prop_t structures in the proper lists. Each new 00121 * @c svn_prop_t structure's fields will point to the same data within 00122 * @a proplist's structures. 00123 * 00124 * Callers may pass NULL for each of the property lists in which they 00125 * are uninterested. If no props exist in a certain category, and the 00126 * property list argument for that category is non-NULL, then that 00127 * array will come back with <tt>->nelts == 0</tt>. 00128 * 00129 * ### Hmmm, maybe a better future interface is to return an array of 00130 * arrays, where the index into the array represents the index 00131 * into @c svn_prop_kind_t. That way we can add more prop kinds 00132 * in the future without changing this interface... 00133 */ 00134 svn_error_t *svn_categorize_props (const apr_array_header_t *proplist, 00135 apr_array_header_t **entry_props, 00136 apr_array_header_t **wc_props, 00137 apr_array_header_t **regular_props, 00138 apr_pool_t *pool); 00139 00140 00141 /** Given two property hashes (<tt>const char *name</tt> -> <tt>const 00142 * svn_string_t *value</tt>), deduce the differences between them (from 00143 * @a source_props -> @c target_props). Return these changes as a series of 00144 * @c svn_prop_t structures stored in @a propdiffs, allocated from @a pool. 00145 * 00146 * For note, here's a quick little table describing the logic of this 00147 * routine: 00148 * 00149 *<pre> basehash localhash event 00150 * -------- --------- ----- 00151 * value = foo value = NULL Deletion occurred. 00152 * value = foo value = bar Set occurred (modification) 00153 * value = NULL value = baz Set occurred (creation)</pre> 00154 */ 00155 svn_error_t *svn_prop_diffs (apr_array_header_t **propdiffs, 00156 apr_hash_t *target_props, 00157 apr_hash_t *source_props, 00158 apr_pool_t *pool); 00159 00160 00161 00162 /* Defines for reserved ("svn:") property names. */ 00163 00164 /** All Subversion property names start with this. */ 00165 #define SVN_PROP_PREFIX "svn:" 00166 00167 00168 /** Visible properties 00169 * 00170 * These are regular properties that are attached to ordinary files 00171 * and dirs, and are visible (and tweakable) by svn client programs 00172 * and users. Adding these properties causes specific effects. 00173 * 00174 * @note the values of these properties are always UTF8-encoded with 00175 * LF line-endings. It is the burden of svn library users to enforce 00176 * this. Use svn_prop_needs_translation() to discover if a 00177 * certain property needs translation, and you can use 00178 * svn_subst_translate_string()/svn_subst_detranslate_string() 00179 * to do the translation. 00180 * 00181 * @defgroup svn_prop_visible_props Visible properties 00182 * @{ 00183 */ 00184 00185 /** The mime-type of a given file. */ 00186 #define SVN_PROP_MIME_TYPE SVN_PROP_PREFIX "mime-type" 00187 00188 /** The ignore patterns for a given directory. */ 00189 #define SVN_PROP_IGNORE SVN_PROP_PREFIX "ignore" 00190 00191 /** The line ending style for a given file. */ 00192 #define SVN_PROP_EOL_STYLE SVN_PROP_PREFIX "eol-style" 00193 00194 /** The "activated" keywords (for keyword substitution) for a given file. */ 00195 #define SVN_PROP_KEYWORDS SVN_PROP_PREFIX "keywords" 00196 00197 /** Set to either TRUE or FALSE if we want a file to be executable or not. */ 00198 #define SVN_PROP_EXECUTABLE SVN_PROP_PREFIX "executable" 00199 00200 /** The value to force the executable property to when set */ 00201 #define SVN_PROP_EXECUTABLE_VALUE "*" 00202 00203 /** Set to TRUE ('*') if we want a file to be set to read-only when 00204 * not locked. FALSE is indicated by deleting the property. */ 00205 #define SVN_PROP_NEEDS_LOCK SVN_PROP_PREFIX "needs-lock" 00206 00207 /** The value to force the needs-lock property to when set */ 00208 #define SVN_PROP_NEEDS_LOCK_VALUE "*" 00209 00210 /** Set if the file should be treated as a special file. */ 00211 #define SVN_PROP_SPECIAL SVN_PROP_PREFIX "special" 00212 00213 /** The value to force the special property to when set. */ 00214 #define SVN_PROP_SPECIAL_VALUE "*" 00215 00216 /** Describes external items to check out into this directory. 00217 * 00218 * The format is a series of lines, such as: 00219 * 00220 *<pre> localdir1 http://url.for.external.source/etc/ 00221 * localdir1/foo http://url.for.external.source/foo 00222 * localdir1/bar http://blah.blah.blah/repositories/theirproj 00223 * localdir1/bar/baz http://blorg.blorg.blorg/basement/code 00224 * localdir2 http://another.url/blah/blah/blah 00225 * localdir3 http://and.so.on/and/so/forth</pre> 00226 * 00227 * The subdir names on the left side are relative to the directory on 00228 * which this property is set. 00229 */ 00230 #define SVN_PROP_EXTERNALS SVN_PROP_PREFIX "externals" 00231 00232 /** @} */ 00233 00234 /** WC props are props that are invisible to users: they're generated 00235 * by an RA layer, and stored in secret parts of .svn/. 00236 * 00237 * @defgroup svn_prop_invisible_props Invisible properties 00238 * @{ 00239 */ 00240 00241 /** The propname *prefix* that makes a propname a "WC property". 00242 * 00243 * For example, ra_dav might store a versioned-resource url as a WC 00244 * prop like this: 00245 * 00246 *<pre> name = svn:wc:dav_url 00247 * val = http://www.lyra.org/repos/452348/e.289</pre> 00248 * 00249 * The client will try to protect WC props by warning users against 00250 * changing them. The client will also send them back to the RA layer 00251 * when committing. 00252 */ 00253 #define SVN_PROP_WC_PREFIX SVN_PROP_PREFIX "wc:" 00254 00255 /** Another type of non-user-visible property. "Entry properties" are 00256 * stored as fields with the administrative 'entries' file. 00257 */ 00258 #define SVN_PROP_ENTRY_PREFIX SVN_PROP_PREFIX "entry:" 00259 00260 /** The revision this entry was last committed to on. */ 00261 #define SVN_PROP_ENTRY_COMMITTED_REV SVN_PROP_ENTRY_PREFIX "committed-rev" 00262 00263 /** The date this entry was last committed to on. */ 00264 #define SVN_PROP_ENTRY_COMMITTED_DATE SVN_PROP_ENTRY_PREFIX "committed-date" 00265 00266 /** The author who last committed to this entry. */ 00267 #define SVN_PROP_ENTRY_LAST_AUTHOR SVN_PROP_ENTRY_PREFIX "last-author" 00268 00269 /** The UUID of this entry's repository. */ 00270 #define SVN_PROP_ENTRY_UUID SVN_PROP_ENTRY_PREFIX "uuid" 00271 00272 /** The lock token for this entry. 00273 * @since New in 1.2. */ 00274 #define SVN_PROP_ENTRY_LOCK_TOKEN SVN_PROP_ENTRY_PREFIX "lock-token" 00275 00276 /** When custom, user-defined properties are passed over the wire, they will 00277 * have this prefix added to their name. 00278 */ 00279 #define SVN_PROP_CUSTOM_PREFIX SVN_PROP_PREFIX "custom:" 00280 00281 /** @} */ 00282 00283 /** 00284 * These are reserved properties attached to a "revision" object in 00285 * the repository filesystem. They can be queried by using 00286 * svn_fs_revision_prop(). They are invisible to svn clients. 00287 * 00288 * @defgroup svn_props_revision_props Revision properties 00289 * @{ 00290 */ 00291 00292 /** The fs revision property that stores a commit's author. */ 00293 #define SVN_PROP_REVISION_AUTHOR SVN_PROP_PREFIX "author" 00294 00295 /** The fs revision property that stores a commit's log message. */ 00296 #define SVN_PROP_REVISION_LOG SVN_PROP_PREFIX "log" 00297 00298 /** The fs revision property that stores a commit's date. */ 00299 #define SVN_PROP_REVISION_DATE SVN_PROP_PREFIX "date" 00300 00301 /** The fs revision property that stores a commit's "original" date. 00302 * 00303 * The svn:date property must be monotonically increasing, along with 00304 * the revision number. In certain scenarios, this may pose a problem 00305 * when the revision represents a commit that occurred at a time which 00306 * does not fit within the sequencing required for svn:date. This can 00307 * happen, for instance, when the revision represents a commit to a 00308 * foreign version control system, or possibly when two Subversion 00309 * repositories are combined. This property can be used to record the 00310 * true, original date of the commit. 00311 */ 00312 #define SVN_PROP_REVISION_ORIG_DATE SVN_PROP_PREFIX "original-date" 00313 00314 /** The presence of this fs revision property indicates that the 00315 * revision was automatically generated by the mod_dav_svn 00316 * autoversioning feature. The value is irrelevant. 00317 */ 00318 #define SVN_PROP_REVISION_AUTOVERSIONED SVN_PROP_PREFIX "autoversioned" 00319 00320 /** 00321 * This is a list of all revision properties. 00322 */ 00323 #define SVN_PROP_REVISION_ALL_PROPS SVN_PROP_REVISION_AUTHOR, \ 00324 SVN_PROP_REVISION_LOG, \ 00325 SVN_PROP_REVISION_DATE, \ 00326 SVN_PROP_REVISION_AUTOVERSIONED, \ 00327 SVN_PROP_REVISION_ORIG_DATE, 00328 00329 /** @} */ 00330 00331 00332 00333 #ifdef __cplusplus 00334 } 00335 #endif /* __cplusplus */ 00336 00337 #endif /* SVN_PROPS_H */