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