Subversion
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
svn_types.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_types.h
24  * @brief Subversion's data types
25  */
26 
27 #ifndef SVN_TYPES_H
28 #define SVN_TYPES_H
29 
30 /* ### this should go away, but it causes too much breakage right now */
31 #include <stdlib.h>
32 #include <limits.h> /* for ULONG_MAX */
33 
34 #include <apr.h> /* for apr_size_t, apr_int64_t, ... */
35 #include <apr_version.h>
36 #include <apr_errno.h> /* for apr_status_t */
37 #include <apr_pools.h> /* for apr_pool_t */
38 #include <apr_hash.h> /* for apr_hash_t */
39 #include <apr_tables.h> /* for apr_array_push() */
40 #include <apr_time.h> /* for apr_time_t */
41 #include <apr_strings.h> /* for apr_atoi64() */
42 
43 #ifdef __cplusplus
44 extern "C" {
45 #endif /* __cplusplus */
46 
47 
48 
49 /** Macro used to mark deprecated functions.
50  *
51  * @since New in 1.6.
52  */
53 #ifndef SVN_DEPRECATED
54 # if !defined(SWIGPERL) && !defined(SWIGPYTHON) && !defined(SWIGRUBY)
55 # if defined(__GNUC__) && (__GNUC__ >= 4 || (__GNUC__==3 && __GNUC_MINOR__>=1))
56 # define SVN_DEPRECATED __attribute__((deprecated))
57 # elif defined(_MSC_VER) && _MSC_VER >= 1300
58 # define SVN_DEPRECATED __declspec(deprecated)
59 # else
60 # define SVN_DEPRECATED
61 # endif
62 # else
63 # define SVN_DEPRECATED
64 # endif
65 #endif
66 
67 
68 /** Macro used to mark experimental functions.
69  *
70  * @since New in 1.9.
71  */
72 #ifndef SVN_EXPERIMENTAL
73 # if !defined(SWIGPERL) && !defined(SWIGPYTHON) && !defined(SWIGRUBY)
74 # if defined(__has_attribute)
75 # if __has_attribute(__warning__)
76 # define SVN_EXPERIMENTAL __attribute__((warning("experimental function used")))
77 # else
78 # define SVN_EXPERIMENTAL
79 # endif
80 # elif !defined(__llvm__) && defined(__GNUC__) \
81  && (__GNUC__ >= 4 || (__GNUC__==3 && __GNUC_MINOR__>=1))
82 # define SVN_EXPERIMENTAL __attribute__((warning("experimental function used")))
83 # elif defined(_MSC_VER) && _MSC_VER >= 1300
84 # define SVN_EXPERIMENTAL __declspec(deprecated("experimental function used"))
85 # else
86 # define SVN_EXPERIMENTAL
87 # endif
88 # else
89 # define SVN_EXPERIMENTAL
90 # endif
91 #endif
92 
93 /** Macro used to mark functions that require a final null sentinel argument.
94  *
95  * @since New in 1.9.
96  */
97 #ifndef SVN_NEEDS_SENTINEL_NULL
98 # if defined(__has_attribute)
99 # if __has_attribute(__sentinel__)
100 # define SVN_NEEDS_SENTINEL_NULL __attribute__((sentinel))
101 # else
102 # define SVN_NEEDS_SENTINEL_NULL
103 # endif
104 # elif defined(__GNUC__) && (__GNUC__ >= 4)
105 # define SVN_NEEDS_SENTINEL_NULL __attribute__((sentinel))
106 # else
107 # define SVN_NEEDS_SENTINEL_NULL
108 # endif
109 #endif
110 
111 
112 /** Indicate whether the current platform supports unaligned data access.
113  *
114  * On the majority of machines running SVN (x86 / x64), unaligned access
115  * is much cheaper than repeated aligned access. Define this macro to 1
116  * on those machines.
117  * Unaligned access on other machines (e.g. IA64) will trigger memory
118  * access faults or simply misbehave.
119  *
120  * Note: Some platforms may only support unaligned access for integers
121  * (PowerPC). As a result this macro should only be used to determine
122  * if unaligned access is supported for integers.
123  *
124  * @since New in 1.7.
125  */
126 #ifndef SVN_UNALIGNED_ACCESS_IS_OK
127 # if defined(_M_IX86) || defined(i386) \
128  || defined(_M_X64) || defined(__x86_64) \
129  || defined(__powerpc__) || defined(__ppc__)
130 # define SVN_UNALIGNED_ACCESS_IS_OK 1
131 # else
132 # define SVN_UNALIGNED_ACCESS_IS_OK 0
133 # endif
134 #endif
135 
136 
137 
138 /** YABT: Yet Another Boolean Type */
139 typedef int svn_boolean_t;
140 
141 #ifndef TRUE
142 /** uhh... true */
143 #define TRUE 1
144 #endif /* TRUE */
145 
146 #ifndef FALSE
147 /** uhh... false */
148 #define FALSE 0
149 #endif /* FALSE */
150 
151 
152 
153 /* Declaration of a unique type, never defined, for the SVN_VA_NULL macro.
154  *
155  * NOTE: Private. Not for direct use by third-party code.
156  */
157 struct svn__null_pointer_constant_stdarg_sentinel_t;
158 
159 /** Null pointer constant used as a sentinel in variable argument lists.
160  *
161  * Use of this macro ensures that the argument is of the correct size when a
162  * pointer is expected. (The macro @c NULL is not defined as a pointer on
163  * all systems, and the arguments to variadic functions are not converted
164  * automatically to the expected type.)
165  *
166  * @since New in 1.9.
167  */
168 #define SVN_VA_NULL ((struct svn__null_pointer_constant_stdarg_sentinel_t*)0)
169 /* See? (char*)NULL -- They have the same length, but the cast looks ugly. */
170 
171 
172 
173 /** Subversion error object.
174  *
175  * Defined here, rather than in svn_error.h, to avoid a recursive @#include
176  * situation.
177  */
178 typedef struct svn_error_t
179 {
180  /** APR error value; possibly an SVN_ custom error code (see
181  * `svn_error_codes.h' for a full listing).
182  */
183  apr_status_t apr_err;
184 
185  /** Details from the producer of error.
186  *
187  * Note that if this error was generated by Subversion's API, you'll
188  * probably want to use svn_err_best_message() to get a single
189  * descriptive string for this error chain (see the @a child member)
190  * or svn_handle_error2() to print the error chain in full. This is
191  * because Subversion's API functions sometimes add many links to
192  * the error chain that lack details (used only to produce virtual
193  * stack traces). (Use svn_error_purge_tracing() to remove those
194  * trace-only links from the error chain.)
195  */
196  const char *message;
197 
198  /** Pointer to the error we "wrap" (may be @c NULL). Via this
199  * member, individual error object can be strung together into an
200  * "error chain".
201  */
203 
204  /** The pool in which this error object is allocated. (If
205  * Subversion's APIs are used to manage error chains, then this pool
206  * will contain the whole error chain of which this object is a
207  * member.) */
208  apr_pool_t *pool;
209 
210  /** Source file where the error originated (iff @c SVN_DEBUG;
211  * undefined otherwise).
212  */
213  const char *file;
214 
215  /** Source line where the error originated (iff @c SVN_DEBUG;
216  * undefined otherwise).
217  */
218  long line;
219 
220 } svn_error_t;
221 
222 
223 
224 /* See svn_version.h.
225  Defined here to avoid including svn_version.h from all public headers. */
226 typedef struct svn_version_t svn_version_t;
227 
228 
229 
230 /** @defgroup APR_ARRAY_compat_macros APR Array Compatibility Helper Macros
231  * These macros are provided by APR itself from version 1.3.
232  * Definitions are provided here for when using older versions of APR.
233  * @{
234  */
235 
236 /** index into an apr_array_header_t */
237 #ifndef APR_ARRAY_IDX
238 #define APR_ARRAY_IDX(ary,i,type) (((type *)(ary)->elts)[i])
239 #endif
240 
241 /** easier array-pushing syntax */
242 #ifndef APR_ARRAY_PUSH
243 #define APR_ARRAY_PUSH(ary,type) (*((type *)apr_array_push(ary)))
244 #endif
245 
246 /** @} */
247 
248 
249 
250 /** @defgroup apr_hash_utilities APR Hash Table Helpers
251  * These functions enable the caller to dereference an APR hash table index
252  * without type casts or temporary variables.
253  *
254  * These functions are provided by APR itself from version 1.5.
255  * Definitions are provided here for when using older versions of APR.
256  * @{
257  */
258 
259 #if !APR_VERSION_AT_LEAST(1, 5, 0)
260 
261 /** Return the key of the hash table entry indexed by @a hi. */
262 const void *
263 apr_hash_this_key(apr_hash_index_t *hi);
264 
265 /** Return the key length of the hash table entry indexed by @a hi. */
266 apr_ssize_t
267 apr_hash_this_key_len(apr_hash_index_t *hi);
268 
269 /** Return the value of the hash table entry indexed by @a hi. */
270 void *
271 apr_hash_this_val(apr_hash_index_t *hi);
272 
273 #endif
274 
275 /** @} */
276 
277 
278 
279 /** On Windows, APR_STATUS_IS_ENOTDIR includes several kinds of
280  * invalid-pathname error but not ERROR_INVALID_NAME, so we include it.
281  * We also include ERROR_DIRECTORY as that was not included in apr versions
282  * before 1.4.0 and this fix is not backported */
283 /* ### These fixes should go into APR. */
284 #ifndef WIN32
285 #define SVN__APR_STATUS_IS_ENOTDIR(s) APR_STATUS_IS_ENOTDIR(s)
286 #else
287 #define SVN__APR_STATUS_IS_ENOTDIR(s) (APR_STATUS_IS_ENOTDIR(s) \
288  || ((s) == APR_OS_START_SYSERR + ERROR_DIRECTORY) \
289  || ((s) == APR_OS_START_SYSERR + ERROR_INVALID_NAME))
290 #endif
291 
292 /** On Windows, APR_STATUS_IS_EPIPE does not include ERROR_NO_DATA error.
293  * So we include it.*/
294 /* ### These fixes should go into APR. */
295 #ifndef WIN32
296 #define SVN__APR_STATUS_IS_EPIPE(s) APR_STATUS_IS_EPIPE(s)
297 #else
298 #define SVN__APR_STATUS_IS_EPIPE(s) (APR_STATUS_IS_EPIPE(s) \
299  || ((s) == APR_OS_START_SYSERR + ERROR_NO_DATA))
300 #endif
301 
302 /** @} */
303 
304 
305 
306 /** The various types of nodes in the Subversion filesystem. */
307 typedef enum svn_node_kind_t
308 {
309  /** absent */
311 
312  /** regular file */
314 
315  /** directory */
317 
318  /** something's here, but we don't know what */
320 
321  /**
322  * symbolic link
323  * @note This value is not currently used by the public API.
324  * @since New in 1.8.
325  */
328 
329 /** Return a constant string expressing @a kind as an English word, e.g.,
330  * "file", "dir", etc. The string is not localized, as it may be used for
331  * client<->server communications. If the kind is not recognized, return
332  * "unknown".
333  *
334  * @since New in 1.6.
335  */
336 const char *
338 
339 /** Return the appropriate node_kind for @a word. @a word is as
340  * returned from svn_node_kind_to_word(). If @a word does not
341  * represent a recognized kind or is @c NULL, return #svn_node_unknown.
342  *
343  * @since New in 1.6.
344  */
346 svn_node_kind_from_word(const char *word);
347 
348 
349 /** Generic three-state property to represent an unknown value for values
350  * that are just like booleans. The values have been set deliberately to
351  * make tristates disjoint from #svn_boolean_t.
352  *
353  * @note It is unsafe to use apr_pcalloc() to allocate these, since '0' is
354  * not a valid value.
355  *
356  * @since New in 1.7. */
357 typedef enum svn_tristate_t
358 {
359  /** state known to be false (the constant does not evaulate to false) */
361  /** state known to be true */
363  /** state could be true or false */
366 
367 /** Return a constant string "true", "false" or NULL representing the value of
368  * @a tristate.
369  *
370  * @since New in 1.7.
371  */
372 const char *
374 
375 /** Return the appropriate tristate for @a word. If @a word is "true", returns
376  * #svn_tristate_true; if @a word is "false", returns #svn_tristate_false,
377  * for all other values (including NULL) returns #svn_tristate_unknown.
378  *
379  * @since New in 1.7.
380  */
382 svn_tristate__from_word(const char * word);
383 
384 
385 
386 /** About Special Files in Subversion
387  *
388  * Subversion denotes files that cannot be portably created or
389  * modified as "special" files (svn_node_special). It stores these
390  * files in the repository as a plain text file with the svn:special
391  * property set. The file contents contain: a platform-specific type
392  * string, a space character, then any information necessary to create
393  * the file on a supported platform. For example, if a symbolic link
394  * were being represented, the repository file would have the
395  * following contents:
396  *
397  * "link /path/to/link/target"
398  *
399  * Where 'link' is the identifier string showing that this special
400  * file should be a symbolic link and '/path/to/link/target' is the
401  * destination of the symbolic link.
402  *
403  * Special files are stored in the text-base exactly as they are
404  * stored in the repository. The platform specific files are created
405  * in the working copy at EOL/keyword translation time using
406  * svn_subst_copy_and_translate2(). If the current platform does not
407  * support a specific special file type, the file is copied into the
408  * working copy as it is seen in the repository. Because of this,
409  * users of other platforms can still view and modify the special
410  * files, even if they do not have their unique properties.
411  *
412  * New types of special files can be added by:
413  * 1. Implementing a platform-dependent routine to create a uniquely
414  * named special file and one to read the special file in
415  * libsvn_subr/io.c.
416  * 2. Creating a new textual name similar to
417  * SVN_SUBST__SPECIAL_LINK_STR in libsvn_subr/subst.c.
418  * 3. Handling the translation/detranslation case for the new type in
419  * create_special_file and detranslate_special_file, using the
420  * routines from 1.
421  */
422 
423 
424 
425 /** A revision number. */
426 typedef long int svn_revnum_t;
427 
428 /** Valid revision numbers begin at 0 */
429 #define SVN_IS_VALID_REVNUM(n) ((n) >= 0)
430 
431 /** The 'official' invalid revision num */
432 #define SVN_INVALID_REVNUM ((svn_revnum_t) -1)
433 
434 /** Not really invalid...just unimportant -- one day, this can be its
435  * own unique value, for now, just make it the same as
436  * #SVN_INVALID_REVNUM.
437  */
438 #define SVN_IGNORED_REVNUM ((svn_revnum_t) -1)
439 
440 /** Convert NULL-terminated C string @a str to a revision number. */
441 #define SVN_STR_TO_REV(str) ((svn_revnum_t) atol(str))
442 
443 /**
444  * Parse NULL-terminated C string @a str as a revision number and
445  * store its value in @a rev. If @a endptr is non-NULL, then the
446  * address of the first non-numeric character in @a str is stored in
447  * it. If there are no digits in @a str, then @a endptr is set (if
448  * non-NULL), and the error #SVN_ERR_REVNUM_PARSE_FAILURE error is
449  * returned. Negative numbers parsed from @a str are considered
450  * invalid, and result in the same error.
451  *
452  * @since New in 1.5.
453  */
454 svn_error_t *
455 svn_revnum_parse(svn_revnum_t *rev,
456  const char *str,
457  const char **endptr);
458 
459 /** Originally intended to be used in printf()-style functions to format
460  * revision numbers. Deprecated due to incompatibilities with language
461  * translation tools (e.g. gettext).
462  *
463  * New code should use a bare "%ld" format specifier for formatting revision
464  * numbers.
465  *
466  * @deprecated Provided for backward compatibility with the 1.0 API.
467  */
468 #define SVN_REVNUM_T_FMT "ld"
469 
470 
471 
472 /** The size of a file in the Subversion FS. */
473 typedef apr_int64_t svn_filesize_t;
474 
475 /** The 'official' invalid file size constant. */
476 #define SVN_INVALID_FILESIZE ((svn_filesize_t) -1)
477 
478 /** In printf()-style functions, format file sizes using this. */
479 #define SVN_FILESIZE_T_FMT APR_INT64_T_FMT
480 
481 #ifndef DOXYGEN_SHOULD_SKIP_THIS
482 /* Parse a base-10 numeric string into a 64-bit unsigned numeric value. */
483 /* NOTE: Private. For use by Subversion's own code only. See issue #1644. */
484 /* FIXME: APR should supply a function to do this, such as "apr_atoui64". */
485 #define svn__atoui64(X) ((apr_uint64_t) apr_atoi64(X))
486 #endif
487 
488 
489 
490 /** An enum to indicate whether recursion is needed. */
492 {
493  svn_nonrecursive = 1,
494  svn_recursive
495 };
496 
497 /** The concept of depth for directories.
498  *
499  * @note This is similar to, but not exactly the same as, the WebDAV
500  * and LDAP concepts of depth.
501  *
502  * @since New in 1.5.
503  */
504 typedef enum svn_depth_t
505 {
506  /* The order of these depths is important: the higher the number,
507  the deeper it descends. This allows us to compare two depths
508  numerically to decide which should govern. */
509 
510  /** Depth undetermined or ignored. In some contexts, this means the
511  client should choose an appropriate default depth. The server
512  will generally treat it as #svn_depth_infinity. */
514 
515  /** Exclude (i.e., don't descend into) directory D.
516  @note In Subversion 1.5, svn_depth_exclude is *not* supported
517  anywhere in the client-side (libsvn_wc/libsvn_client/etc) code;
518  it is only supported as an argument to set_path functions in the
519  ra and repos reporters. (This will enable future versions of
520  Subversion to run updates, etc, against 1.5 servers with proper
521  svn_depth_exclude behavior, once we get a chance to implement
522  client-side support for svn_depth_exclude.)
523  */
525 
526  /** Just the named directory D, no entries. Updates will not pull in
527  any files or subdirectories not already present. */
529 
530  /** D + its file children, but not subdirs. Updates will pull in any
531  files not already present, but not subdirectories. */
533 
534  /** D + immediate children (D and its entries). Updates will pull in
535  any files or subdirectories not already present; those
536  subdirectories' this_dir entries will have depth-empty. */
538 
539  /** D + all descendants (full recursion from D). Updates will pull
540  in any files or subdirectories not already present; those
541  subdirectories' this_dir entries will have depth-infinity.
542  Equivalent to the pre-1.5 default update behavior. */
544 
545 } svn_depth_t;
546 
547 /** Return a constant string expressing @a depth as an English word,
548  * e.g., "infinity", "immediates", etc. The string is not localized,
549  * as it may be used for client<->server communications.
550  *
551  * @since New in 1.5.
552  */
553 const char *
555 
556 /** Return the appropriate depth for @a depth_str. @a word is as
557  * returned from svn_depth_to_word(). If @a depth_str does not
558  * represent a recognized depth, return #svn_depth_unknown.
559  *
560  * @since New in 1.5.
561  */
563 svn_depth_from_word(const char *word);
564 
565 /** Return #svn_depth_infinity if boolean @a recurse is TRUE, else
566  * return #svn_depth_files.
567  *
568  * @note New code should never need to use this, it is called only
569  * from pre-depth APIs, for compatibility.
570  *
571  * @since New in 1.5.
572  */
573 #define SVN_DEPTH_INFINITY_OR_FILES(recurse) \
574  ((recurse) ? svn_depth_infinity : svn_depth_files)
575 
576 /** Return #svn_depth_infinity if boolean @a recurse is TRUE, else
577  * return #svn_depth_immediates.
578  *
579  * @note New code should never need to use this, it is called only
580  * from pre-depth APIs, for compatibility.
581  *
582  * @since New in 1.5.
583  */
584 #define SVN_DEPTH_INFINITY_OR_IMMEDIATES(recurse) \
585  ((recurse) ? svn_depth_infinity : svn_depth_immediates)
586 
587 /** Return #svn_depth_infinity if boolean @a recurse is TRUE, else
588  * return #svn_depth_empty.
589  *
590  * @note New code should never need to use this, it is called only
591  * from pre-depth APIs, for compatibility.
592  *
593  * @since New in 1.5.
594  */
595 #define SVN_DEPTH_INFINITY_OR_EMPTY(recurse) \
596  ((recurse) ? svn_depth_infinity : svn_depth_empty)
597 
598 /** Return a recursion boolean based on @a depth.
599  *
600  * Although much code has been converted to use depth, some code still
601  * takes a recurse boolean. In most cases, it makes sense to treat
602  * unknown or infinite depth as recursive, and any other depth as
603  * non-recursive (which in turn usually translates to #svn_depth_files).
604  */
605 #define SVN_DEPTH_IS_RECURSIVE(depth) \
606  ((depth) == svn_depth_infinity || (depth) == svn_depth_unknown)
607 
608 
609 
610 /**
611  * It is sometimes convenient to indicate which parts of an #svn_dirent_t
612  * object you are actually interested in, so that calculating and sending
613  * the data corresponding to the other fields can be avoided. These values
614  * can be used for that purpose.
615  *
616  * @defgroup svn_dirent_fields Dirent fields
617  * @{
618  */
619 
620 /** An indication that you are interested in the @c kind field */
621 #define SVN_DIRENT_KIND 0x00001
622 
623 /** An indication that you are interested in the @c size field */
624 #define SVN_DIRENT_SIZE 0x00002
625 
626 /** An indication that you are interested in the @c has_props field */
627 #define SVN_DIRENT_HAS_PROPS 0x00004
628 
629 /** An indication that you are interested in the @c created_rev field */
630 #define SVN_DIRENT_CREATED_REV 0x00008
631 
632 /** An indication that you are interested in the @c time field */
633 #define SVN_DIRENT_TIME 0x00010
634 
635 /** An indication that you are interested in the @c last_author field */
636 #define SVN_DIRENT_LAST_AUTHOR 0x00020
637 
638 /** A combination of all the dirent fields */
639 #define SVN_DIRENT_ALL ~((apr_uint32_t ) 0)
640 
641 /** @} */
642 
643 /** A general subversion directory entry.
644  *
645  * @note To allow for extending the #svn_dirent_t structure in future
646  * releases, always use svn_dirent_create() to allocate the stucture.
647  *
648  * @since New in 1.6.
649  */
650 typedef struct svn_dirent_t
651 {
652  /** node kind */
654 
655  /** length of file text, or 0 for directories */
656  svn_filesize_t size;
657 
658  /** does the node have props? */
659  svn_boolean_t has_props;
660 
661  /** last rev in which this node changed */
662  svn_revnum_t created_rev;
663 
664  /** time of created_rev (mod-time) */
665  apr_time_t time;
666 
667  /** author of created_rev */
668  const char *last_author;
669 
670  /* IMPORTANT: If you extend this struct, check svn_dirent_dup(). */
671 } svn_dirent_t;
672 
673 /** Return a deep copy of @a dirent, allocated in @a pool.
674  *
675  * @since New in 1.4.
676  */
677 svn_dirent_t *
678 svn_dirent_dup(const svn_dirent_t *dirent,
679  apr_pool_t *pool);
680 
681 /**
682  * Create a new svn_dirent_t instance with all values initialized to their
683  * not-available values.
684  *
685  * @since New in 1.8.
686  */
687 svn_dirent_t *
688 svn_dirent_create(apr_pool_t *result_pool);
689 
690 
691 /** Keyword substitution.
692  *
693  * All the keywords Subversion recognizes.
694  *
695  * Note that there is a better, more general proposal out there, which
696  * would take care of both internationalization issues and custom
697  * keywords (e.g., $NetBSD$). See
698  *
699  * @verbatim
700  http://subversion.tigris.org/servlets/ReadMsg?list=dev&msgNo=8921
701  =====
702  From: "Jonathan M. Manning" <jmanning@alisa-jon.net>
703  To: dev@subversion.tigris.org
704  Date: Fri, 14 Dec 2001 11:56:54 -0500
705  Message-ID: <87970000.1008349014@bdldevel.bl.bdx.com>
706  Subject: Re: keywords @endverbatim
707  *
708  * and Eric Gillespie's support of same:
709  *
710  * @verbatim
711  http://subversion.tigris.org/servlets/ReadMsg?list=dev&msgNo=8757
712  =====
713  From: "Eric Gillespie, Jr." <epg@pretzelnet.org>
714  To: dev@subversion.tigris.org
715  Date: Wed, 12 Dec 2001 09:48:42 -0500
716  Message-ID: <87k7vsebp1.fsf@vger.pretzelnet.org>
717  Subject: Re: Customizable Keywords @endverbatim
718  *
719  * However, it is considerably more complex than the scheme below.
720  * For now we're going with simplicity, hopefully the more general
721  * solution can be done post-1.0.
722  *
723  * @defgroup svn_types_keywords Keyword definitions
724  * @{
725  */
726 
727 /** The maximum size of an expanded or un-expanded keyword. */
728 #define SVN_KEYWORD_MAX_LEN 255
729 
730 /** The most recent revision in which this file was changed. */
731 #define SVN_KEYWORD_REVISION_LONG "LastChangedRevision"
732 
733 /** Short version of LastChangedRevision */
734 #define SVN_KEYWORD_REVISION_SHORT "Rev"
735 
736 /** Medium version of LastChangedRevision, matching the one CVS uses.
737  * @since New in 1.1. */
738 #define SVN_KEYWORD_REVISION_MEDIUM "Revision"
739 
740 /** The most recent date (repository time) when this file was changed. */
741 #define SVN_KEYWORD_DATE_LONG "LastChangedDate"
742 
743 /** Short version of LastChangedDate */
744 #define SVN_KEYWORD_DATE_SHORT "Date"
745 
746 /** Who most recently committed to this file. */
747 #define SVN_KEYWORD_AUTHOR_LONG "LastChangedBy"
748 
749 /** Short version of LastChangedBy */
750 #define SVN_KEYWORD_AUTHOR_SHORT "Author"
751 
752 /** The URL for the head revision of this file. */
753 #define SVN_KEYWORD_URL_LONG "HeadURL"
754 
755 /** Short version of HeadURL */
756 #define SVN_KEYWORD_URL_SHORT "URL"
757 
758 /** A compressed combination of the other four keywords. */
759 #define SVN_KEYWORD_ID "Id"
760 
761 /** A full combination of the first four keywords.
762  * @since New in 1.6. */
763 #define SVN_KEYWORD_HEADER "Header"
764 
765 /** @} */
766 
767 
768 
769 /** All information about a commit.
770  *
771  * @note Objects of this type should always be created using the
772  * svn_create_commit_info() function.
773  *
774  * @since New in 1.3.
775  */
776 typedef struct svn_commit_info_t
777 {
778  /** just-committed revision. */
779  svn_revnum_t revision;
780 
781  /** server-side date of the commit. */
782  const char *date;
783 
784  /** author of the commit. */
785  const char *author;
786 
787  /** error message from post-commit hook, or NULL. */
788  const char *post_commit_err;
789 
790  /** repository root, may be @c NULL if unknown.
791  @since New in 1.7. */
792  const char *repos_root;
793 
795 
796 /**
797  * Allocate an object of type #svn_commit_info_t in @a pool and
798  * return it.
799  *
800  * The @c revision field of the new struct is set to #SVN_INVALID_REVNUM.
801  * All other fields are initialized to @c NULL.
802  *
803  * @note Any object of the type #svn_commit_info_t should
804  * be created using this function.
805  * This is to provide for extending the svn_commit_info_t in
806  * the future.
807  *
808  * @since New in 1.3.
809  */
811 svn_create_commit_info(apr_pool_t *pool);
812 
813 /**
814  * Return a deep copy @a src_commit_info allocated in @a pool.
815  *
816  * @since New in 1.4.
817  */
819 svn_commit_info_dup(const svn_commit_info_t *src_commit_info,
820  apr_pool_t *pool);
821 
822 
823 
824 /**
825  * A structure to represent a path that changed for a log entry.
826  *
827  * @note To allow for extending the #svn_log_changed_path2_t structure in
828  * future releases, always use svn_log_changed_path2_create() to allocate
829  * the structure.
830  *
831  * @since New in 1.6.
832  */
834 {
835  /** 'A'dd, 'D'elete, 'R'eplace, 'M'odify */
836  char action;
837 
838  /** Source path of copy (if any). */
839  const char *copyfrom_path;
840 
841  /** Source revision of copy (if any). */
842  svn_revnum_t copyfrom_rev;
843 
844  /** The type of the node, may be svn_node_unknown. */
846 
847  /** Is the text modified, may be svn_tristate_unknown.
848  * @since New in 1.7. */
850 
851  /** Are properties modified, may be svn_tristate_unknown.
852  * @since New in 1.7. */
854 
855  /* NOTE: Add new fields at the end to preserve binary compatibility.
856  Also, if you add fields here, you have to update
857  svn_log_changed_path2_dup(). */
859 
860 /**
861  * Returns an #svn_log_changed_path2_t, allocated in @a pool with all fields
862  * initialized to NULL, None or empty values.
863  *
864  * @note To allow for extending the #svn_log_changed_path2_t structure in
865  * future releases, this function should always be used to allocate the
866  * structure.
867  *
868  * @since New in 1.6.
869  */
871 svn_log_changed_path2_create(apr_pool_t *pool);
872 
873 /**
874  * Return a deep copy of @a changed_path, allocated in @a pool.
875  *
876  * @since New in 1.6.
877  */
880  apr_pool_t *pool);
881 
882 /**
883  * A structure to represent a path that changed for a log entry. Same as
884  * the first three fields of #svn_log_changed_path2_t.
885  *
886  * @deprecated Provided for backward compatibility with the 1.5 API.
887  */
889 {
890  /** 'A'dd, 'D'elete, 'R'eplace, 'M'odify */
891  char action;
892 
893  /** Source path of copy (if any). */
894  const char *copyfrom_path;
895 
896  /** Source revision of copy (if any). */
897  svn_revnum_t copyfrom_rev;
898 
900 
901 /**
902  * Return a deep copy of @a changed_path, allocated in @a pool.
903  *
904  * @since New in 1.3.
905  * @deprecated Provided for backward compatibility with the 1.5 API.
906  */
910  apr_pool_t *pool);
911 
912 /**
913  * A structure to represent all the information about a particular log entry.
914  *
915  * @note To allow for extending the #svn_log_entry_t structure in future
916  * releases, always use svn_log_entry_create() to allocate the structure.
917  *
918  * @since New in 1.5.
919  */
920 typedef struct svn_log_entry_t
921 {
922  /** A hash containing as keys every path committed in @a revision; the
923  * values are (#svn_log_changed_path_t *) structures.
924  *
925  * The subversion core libraries will always set this field to the same
926  * value as changed_paths2 for compatibility reasons.
927  *
928  * @deprecated Provided for backward compatibility with the 1.5 API.
929  */
930  apr_hash_t *changed_paths;
931 
932  /** The revision of the commit. */
933  svn_revnum_t revision;
934 
935  /** The hash of requested revision properties, which may be NULL if it
936  * would contain no revprops. Maps (const char *) property name to
937  * (svn_string_t *) property value. */
938  apr_hash_t *revprops;
939 
940  /**
941  * Whether or not this message has children.
942  *
943  * When a log operation requests additional merge information, extra log
944  * entries may be returned as a result of this entry. The new entries, are
945  * considered children of the original entry, and will follow it. When
946  * the HAS_CHILDREN flag is set, the receiver should increment its stack
947  * depth, and wait until an entry is provided with SVN_INVALID_REVNUM which
948  * indicates the end of the children.
949  *
950  * For log operations which do not request additional merge information, the
951  * HAS_CHILDREN flag is always FALSE.
952  *
953  * For more information see:
954  * https://svn.apache.org/repos/asf/subversion/trunk/notes/merge-tracking/design.html#commutative-reporting
955  */
956  svn_boolean_t has_children;
957 
958  /** A hash containing as keys every path committed in @a revision; the
959  * values are (#svn_log_changed_path2_t *) structures.
960  *
961  * If this value is not @c NULL, it MUST have the same value as
962  * changed_paths or svn_log_entry_dup() will not create an identical copy.
963  *
964  * The subversion core libraries will always set this field to the same
965  * value as changed_paths for compatibility with users assuming an older
966  * version.
967  *
968  * @note See http://svn.haxx.se/dev/archive-2010-08/0362.shtml for
969  * further explanation.
970  *
971  * @since New in 1.6.
972  */
973  apr_hash_t *changed_paths2;
974 
975  /**
976  * Whether @a revision should be interpreted as non-inheritable in the
977  * same sense of #svn_merge_range_t.
978  *
979  * Only set when this #svn_log_entry_t instance is returned by the
980  * libsvn_client mergeinfo apis. Currently always FALSE when the
981  * #svn_log_entry_t instance is reported by the ra layer.
982  *
983  * @since New in 1.7.
984  */
985  svn_boolean_t non_inheritable;
986 
987  /**
988  * Whether @a revision is a merged revision resulting from a reverse merge.
989  *
990  * @since New in 1.7.
991  */
992  svn_boolean_t subtractive_merge;
993 
994  /* NOTE: Add new fields at the end to preserve binary compatibility.
995  Also, if you add fields here, you have to update
996  svn_log_entry_dup(). */
998 
999 /**
1000  * Returns an #svn_log_entry_t, allocated in @a pool with all fields
1001  * initialized to NULL values.
1002  *
1003  * @note To allow for extending the #svn_log_entry_t structure in future
1004  * releases, this function should always be used to allocate the structure.
1005  *
1006  * @since New in 1.5.
1007  */
1009 svn_log_entry_create(apr_pool_t *pool);
1010 
1011 /** Return a deep copy of @a log_entry, allocated in @a pool.
1012  *
1013  * The resulting svn_log_entry_t has @c changed_paths set to the same
1014  * value as @c changed_path2. @c changed_paths will be @c NULL if
1015  * @c changed_paths2 was @c NULL.
1016  *
1017  * @since New in 1.6.
1018  */
1020 svn_log_entry_dup(const svn_log_entry_t *log_entry, apr_pool_t *pool);
1021 
1022 /** The callback invoked by log message loopers, such as
1023  * #svn_ra_plugin_t.get_log() and svn_repos_get_logs().
1024  *
1025  * This function is invoked once on each log message, in the order
1026  * determined by the caller (see above-mentioned functions).
1027  *
1028  * @a baton is what you think it is, and @a log_entry contains relevant
1029  * information for the log message. Any of @a log_entry->author,
1030  * @a log_entry->date, or @a log_entry->message may be @c NULL.
1031  *
1032  * If @a log_entry->date is neither NULL nor the empty string, it was
1033  * generated by svn_time_to_cstring() and can be converted to
1034  * @c apr_time_t with svn_time_from_cstring().
1035  *
1036  * If @a log_entry->changed_paths is non-@c NULL, then it contains as keys
1037  * every path committed in @a log_entry->revision; the values are
1038  * (#svn_log_changed_path_t *) structures.
1039  *
1040  * If @a log_entry->has_children is @c TRUE, the message will be followed
1041  * immediately by any number of merged revisions (child messages), which are
1042  * terminated by an invocation with SVN_INVALID_REVNUM. This usage may
1043  * be recursive.
1044  *
1045  * Use @a pool for temporary allocation. If the caller is iterating
1046  * over log messages, invoking this receiver on each, we recommend the
1047  * standard pool loop recipe: create a subpool, pass it as @a pool to
1048  * each call, clear it after each iteration, destroy it after the loop
1049  * is done. (For allocation that must last beyond the lifetime of a
1050  * given receiver call, use a pool in @a baton.)
1051  *
1052  * @since New in 1.5.
1053  */
1054 typedef svn_error_t *(*svn_log_entry_receiver_t)(
1055  void *baton,
1056  svn_log_entry_t *log_entry,
1057  apr_pool_t *pool);
1058 
1059 /**
1060  * Similar to #svn_log_entry_receiver_t, except this uses separate
1061  * parameters for each part of the log entry.
1062  *
1063  * @deprecated Provided for backward compatibility with the 1.4 API.
1064  */
1065 typedef svn_error_t *(*svn_log_message_receiver_t)(
1066  void *baton,
1067  apr_hash_t *changed_paths,
1068  svn_revnum_t revision,
1069  const char *author,
1070  const char *date, /* use svn_time_from_cstring() if need apr_time_t */
1071  const char *message,
1072  apr_pool_t *pool);
1073 
1074 
1075 /** Callback function type for commits.
1076  *
1077  * When a commit succeeds, an instance of this is invoked with the
1078  * @a commit_info, along with the @a baton closure.
1079  * @a pool can be used for temporary allocations.
1080  *
1081  * @since New in 1.4.
1082  */
1083 typedef svn_error_t *(*svn_commit_callback2_t)(
1084  const svn_commit_info_t *commit_info,
1085  void *baton,
1086  apr_pool_t *pool);
1087 
1088 /** Same as #svn_commit_callback2_t, but uses individual
1089  * data elements instead of the #svn_commit_info_t structure
1090  *
1091  * @deprecated Provided for backward compatibility with the 1.3 API.
1092  */
1093 typedef svn_error_t *(*svn_commit_callback_t)(
1094  svn_revnum_t new_revision,
1095  const char *date,
1096  const char *author,
1097  void *baton);
1098 
1099 
1100 
1101 /** A buffer size that may be used when processing a stream of data.
1102  *
1103  * @note We don't use this constant any longer, since it is considered to be
1104  * unnecessarily large.
1105  *
1106  * @deprecated Provided for backwards compatibility with the 1.3 API.
1107  */
1108 #define SVN_STREAM_CHUNK_SIZE 102400
1109 
1110 #ifndef DOXYGEN_SHOULD_SKIP_THIS
1111 /*
1112  * The maximum amount we (ideally) hold in memory at a time when
1113  * processing a stream of data.
1114  *
1115  * For example, when copying data from one stream to another, do it in
1116  * blocks of this size.
1117  *
1118  * NOTE: This is an internal macro, put here for convenience.
1119  * No public API may depend on the particular value of this macro.
1120  */
1121 #define SVN__STREAM_CHUNK_SIZE 16384
1122 #endif
1123 
1124 /** The maximum amount we can ever hold in memory. */
1125 /* FIXME: Should this be the same as SVN_STREAM_CHUNK_SIZE? */
1126 #define SVN_MAX_OBJECT_SIZE (((apr_size_t) -1) / 2)
1127 
1128 
1129 
1130 /* ### Note: despite being about mime-TYPES, these probably don't
1131  * ### belong in svn_types.h. However, no other header is more
1132  * ### appropriate, and didn't feel like creating svn_validate.h for
1133  * ### so little.
1134  */
1135 
1136 /** Validate @a mime_type.
1137  *
1138  * If @a mime_type does not contain a "/", or ends with non-alphanumeric
1139  * data, return #SVN_ERR_BAD_MIME_TYPE, else return success.
1140  *
1141  * Use @a pool only to find error allocation.
1142  *
1143  * Goal: to match both "foo/bar" and "foo/bar; charset=blah", without
1144  * being too strict about it, but to disallow mime types that have
1145  * quotes, newlines, or other garbage on the end, such as might be
1146  * unsafe in an HTTP header.
1147  */
1148 svn_error_t *
1149 svn_mime_type_validate(const char *mime_type,
1150  apr_pool_t *pool);
1151 
1152 /** Return FALSE iff @a mime_type is a textual type.
1153  *
1154  * All mime types that start with "text/" are textual, plus some special
1155  * cases (for example, "image/x-xbitmap").
1156  */
1157 svn_boolean_t
1158 svn_mime_type_is_binary(const char *mime_type);
1159 
1160 
1161 
1162 /** A user defined callback that subversion will call with a user defined
1163  * baton to see if the current operation should be continued. If the operation
1164  * should continue, the function should return #SVN_NO_ERROR, if not, it
1165  * should return #SVN_ERR_CANCELLED.
1166  */
1167 typedef svn_error_t *(*svn_cancel_func_t)(void *cancel_baton);
1168 
1169 
1170 
1171 /**
1172  * A lock object, for client & server to share.
1173  *
1174  * A lock represents the exclusive right to add, delete, or modify a
1175  * path. A lock is created in a repository, wholly controlled by the
1176  * repository. A "lock-token" is the lock's UUID, and can be used to
1177  * learn more about a lock's fields, and or/make use of the lock.
1178  * Because a lock is immutable, a client is free to not only cache the
1179  * lock-token, but the lock's fields too, for convenience.
1180  *
1181  * Note that the 'is_dav_comment' field is wholly ignored by every
1182  * library except for mod_dav_svn. The field isn't even marshalled
1183  * over the network to the client. Assuming lock structures are
1184  * created with apr_pcalloc(), a default value of 0 is universally safe.
1185  *
1186  * @note in the current implementation, only files are lockable.
1187  *
1188  * @since New in 1.2.
1189  */
1190 typedef struct svn_lock_t
1191 {
1192  const char *path; /**< the path this lock applies to */
1193  const char *token; /**< unique URI representing lock */
1194  const char *owner; /**< the username which owns the lock */
1195  const char *comment; /**< (optional) description of lock */
1196  svn_boolean_t is_dav_comment; /**< was comment made by generic DAV client? */
1197  apr_time_t creation_date; /**< when lock was made */
1198  apr_time_t expiration_date; /**< (optional) when lock will expire;
1199  If value is 0, lock will never expire. */
1200 } svn_lock_t;
1201 
1202 /**
1203  * Returns an #svn_lock_t, allocated in @a pool with all fields initialized
1204  * to NULL values.
1205  *
1206  * @note To allow for extending the #svn_lock_t structure in the future
1207  * releases, this function should always be used to allocate the structure.
1208  *
1209  * @since New in 1.2.
1210  */
1211 svn_lock_t *
1212 svn_lock_create(apr_pool_t *pool);
1213 
1214 /**
1215  * Return a deep copy of @a lock, allocated in @a pool.
1216  *
1217  * @since New in 1.2.
1218  */
1219 svn_lock_t *
1220 svn_lock_dup(const svn_lock_t *lock, apr_pool_t *pool);
1221 
1222 
1223 
1224 /**
1225  * Return a formatted Universal Unique IDentifier (UUID) string.
1226  *
1227  * @since New in 1.4.
1228  */
1229 const char *
1230 svn_uuid_generate(apr_pool_t *pool);
1231 
1232 
1233 
1234 /**
1235  * Mergeinfo representing a merge of a range of revisions.
1236  *
1237  * @since New in 1.5
1238  */
1239 typedef struct svn_merge_range_t
1240 {
1241  /**
1242  * If the 'start' field is less than the 'end' field then 'start' is
1243  * exclusive and 'end' inclusive of the range described. This is termed
1244  * a forward merge range. If 'start' is greater than 'end' then the
1245  * opposite is true. This is termed a reverse merge range. If 'start'
1246  * equals 'end' the meaning of the range is not defined.
1247  */
1248  svn_revnum_t start;
1249  svn_revnum_t end;
1250 
1251  /**
1252  * Whether this merge range should be inherited by treewise
1253  * descendants of the path to which the range applies. */
1254  svn_boolean_t inheritable;
1256 
1257 /**
1258  * Return a copy of @a range, allocated in @a pool.
1259  *
1260  * @since New in 1.5.
1261  */
1263 svn_merge_range_dup(const svn_merge_range_t *range, apr_pool_t *pool);
1264 
1265 /**
1266  * Returns true if the changeset committed in revision @a rev is one
1267  * of the changesets in the range @a range.
1268  *
1269  * @since New in 1.5.
1270  */
1271 svn_boolean_t
1272 svn_merge_range_contains_rev(const svn_merge_range_t *range, svn_revnum_t rev);
1273 
1274 
1275 
1276 /** @defgroup node_location_seg_reporting Node location segment reporting.
1277  * @{ */
1278 
1279 /**
1280  * A representation of a segment of an object's version history with an
1281  * emphasis on the object's location in the repository as of various
1282  * revisions.
1283  *
1284  * @since New in 1.5.
1285  */
1287 {
1288  /** The beginning (oldest) and ending (youngest) revisions for this
1289  segment, both inclusive. */
1290  svn_revnum_t range_start;
1291  svn_revnum_t range_end;
1292 
1293  /** The absolute (sans leading slash) path for this segment. May be
1294  NULL to indicate gaps in an object's history. */
1295  const char *path;
1296 
1298 
1299 /**
1300  * A callback invoked by generators of #svn_location_segment_t
1301  * objects, used to report information about a versioned object's
1302  * history in terms of its location in the repository filesystem over
1303  * time.
1304  */
1305 typedef svn_error_t *(*svn_location_segment_receiver_t)(
1306  svn_location_segment_t *segment,
1307  void *baton,
1308  apr_pool_t *pool);
1309 
1310 /**
1311  * Return a deep copy of @a segment, allocated in @a pool.
1312  *
1313  * @since New in 1.5.
1314  */
1317  apr_pool_t *pool);
1318 
1319 /** @} */
1320 
1321 
1322 
1323 /** A line number, such as in a file or a stream.
1324  *
1325  * @since New in 1.7.
1326  */
1327 typedef unsigned long svn_linenum_t;
1328 
1329 /** The maximum value of an svn_linenum_t.
1330  *
1331  * @since New in 1.7.
1332  */
1333 #define SVN_LINENUM_MAX_VALUE ULONG_MAX
1334 
1335 
1336 
1337 #ifdef __cplusplus
1338 }
1339 #endif /* __cplusplus */
1340 
1341 
1342 /*
1343  * Everybody and their brother needs to deal with svn_error_t, the error
1344  * codes, and whatever else. While they *should* go and include svn_error.h
1345  * in order to do that... bah. Let's just help everybody out and include
1346  * that header whenever somebody grabs svn_types.h.
1347  *
1348  * Note that we do this at the END of this header so that its contents
1349  * are available to svn_error.h (our guards will prevent the circular
1350  * include). We also need to do the include *outside* of the cplusplus
1351  * guard.
1352  */
1353 #include "svn_error.h"
1354 
1355 
1356 /*
1357  * Subversion developers may want to use some additional debugging facilities
1358  * while working on the code. We'll pull that in here, so individual source
1359  * files don't have to include this header manually.
1360  */
1361 #ifdef SVN_DEBUG
1362 #include "private/svn_debug.h"
1363 #endif
1364 
1365 
1366 #endif /* SVN_TYPES_H */