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