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  * Copyright (c) 2000-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_types.h
19  * @brief Subversion's data types
20  */
21 
22 #ifndef SVN_TYPES_H
23 #define SVN_TYPES_H
24 
25 /* ### this should go away, but it causes too much breakage right now */
26 #include <stdlib.h>
27 
28 #include <apr.h> /* for apr_size_t, apr_int64_t, ... */
29 #include <apr_errno.h> /* for apr_status_t */
30 #include <apr_pools.h> /* for apr_pool_t */
31 #include <apr_hash.h> /* for apr_hash_t */
32 #include <apr_tables.h> /* for apr_array_push() */
33 #include <apr_time.h> /* for apr_time_t */
34 #include <apr_strings.h> /* for apr_atoi64() */
35 
36 #ifdef __cplusplus
37 extern "C" {
38 #endif /* __cplusplus */
39 
40 
41 
42 /** Macro used to mark deprecated functions.
43  *
44  * @since New in 1.6.
45  */
46 #ifndef SVN_DEPRECATED
47 #if !defined(SWIGPERL) && !defined(SWIGPYTHON) && !defined(SWIGRUBY)
48 #if defined(__GNUC__) && (__GNUC__ >= 4 || (__GNUC__==3 && __GNUC_MINOR__>=1))
49 #define SVN_DEPRECATED __attribute__((deprecated))
50 #elif defined(_MSC_VER) && _MSC_VER >= 1300
51 #define SVN_DEPRECATED __declspec(deprecated)
52 #else
53 #define SVN_DEPRECATED
54 #endif
55 #else
56 #define SVN_DEPRECATED
57 #endif
58 #endif
59 
60 
61 
62 /** Subversion error object.
63  *
64  * Defined here, rather than in svn_error.h, to avoid a recursive @#include
65  * situation.
66  */
67 typedef struct svn_error_t
68 {
69  /** APR error value, possibly SVN_ custom err */
70  apr_status_t apr_err;
71 
72  /** details from producer of error */
73  const char *message;
74 
75  /** ptr to the error we "wrap" */
76  struct svn_error_t *child;
77 
78  /** The pool holding this error and any child errors it wraps */
79  apr_pool_t *pool;
80 
81  /** Source file where the error originated. Only used iff @c SVN_DEBUG. */
82  const char *file;
83 
84  /** Source line where the error originated. Only used iff @c SVN_DEBUG. */
85  long line;
86 
87 } svn_error_t;
88 
89 
90 
91 /** @defgroup APR_ARRAY_compat_macros APR Array Compatibility Helper Macros
92  * These macros are provided by APR itself from version 1.3.
93  * Definitions are provided here for when using older versions of APR.
94  * @{
95  */
96 
97 /** index into an apr_array_header_t */
98 #ifndef APR_ARRAY_IDX
99 #define APR_ARRAY_IDX(ary,i,type) (((type *)(ary)->elts)[i])
100 #endif
101 
102 /** easier array-pushing syntax */
103 #ifndef APR_ARRAY_PUSH
104 #define APR_ARRAY_PUSH(ary,type) (*((type *)apr_array_push(ary)))
105 #endif
106 
107 /** @} */
108 
109 /** The various types of nodes in the Subversion filesystem. */
110 typedef enum
111 {
112  /** absent */
114 
115  /** regular file */
117 
118  /** directory */
120 
121  /** something's here, but we don't know what */
124 
125 /** Return a constant string expressing @a kind as an English word, e.g.,
126  * "file", "dir", etc. The string is not localized, as it may be used for
127  * client<->server communications. If the kind is not recognized, return
128  * "unknown".
129  *
130  * @since New in 1.6.
131  */
132 const char *
134 
135 /** Return the appropriate node_kind for @a word. @a word is as
136  * returned from svn_node_kind_to_word(). If @a word does not
137  * represent a recognized kind or is @c NULL, return @c svn_node_unknown.
138  *
139  * @since New in 1.6.
140  */
142 svn_node_kind_from_word(const char *word);
143 
144 /** About Special Files in Subversion
145  *
146  * Subversion denotes files that cannot be portably created or
147  * modified as "special" files (svn_node_special). It stores these
148  * files in the repository as a plain text file with the svn:special
149  * property set. The file contents contain: a platform-specific type
150  * string, a space character, then any information necessary to create
151  * the file on a supported platform. For example, if a symbolic link
152  * were being represented, the repository file would have the
153  * following contents:
154  *
155  * "link /path/to/link/target"
156  *
157  * Where 'link' is the identifier string showing that this special
158  * file should be a symbolic link and '/path/to/link/target' is the
159  * destination of the symbolic link.
160  *
161  * Special files are stored in the text-base exactly as they are
162  * stored in the repository. The platform specific files are created
163  * in the working copy at EOL/keyword translation time using
164  * svn_subst_copy_and_translate2(). If the current platform does not
165  * support a specific special file type, the file is copied into the
166  * working copy as it is seen in the repository. Because of this,
167  * users of other platforms can still view and modify the special
168  * files, even if they do not have their unique properties.
169  *
170  * New types of special files can be added by:
171  * 1. Implementing a platform-dependent routine to create a uniquely
172  * named special file and one to read the special file in
173  * libsvn_subr/io.c.
174  * 2. Creating a new textual name similar to
175  * SVN_SUBST__SPECIAL_LINK_STR in libsvn_subr/subst.c.
176  * 3. Handling the translation/detranslation case for the new type in
177  * create_special_file and detranslate_special_file, using the
178  * routines from 1.
179  */
180 
181 /** A revision number. */
182 typedef long int svn_revnum_t;
183 
184 /** Valid revision numbers begin at 0 */
185 #define SVN_IS_VALID_REVNUM(n) ((n) >= 0)
186 
187 /** The 'official' invalid revision num */
188 #define SVN_INVALID_REVNUM ((svn_revnum_t) -1)
189 
190 /** Not really invalid...just unimportant -- one day, this can be its
191  * own unique value, for now, just make it the same as
192  * @c SVN_INVALID_REVNUM.
193  */
194 #define SVN_IGNORED_REVNUM ((svn_revnum_t) -1)
195 
196 /** Convert NULL-terminated C string @a str to a revision number. */
197 #define SVN_STR_TO_REV(str) ((svn_revnum_t) atol(str))
198 
199 /**
200  * Parse NULL-terminated C string @a str as a revision number and
201  * store its value in @a rev. If @a endptr is non-NULL, then the
202  * address of the first non-numeric character in @a str is stored in
203  * it. If there are no digits in @a str, then @a endptr is set (if
204  * non-NULL), and the error @c SVN_ERR_REVNUM_PARSE_FAILURE error is
205  * returned. Negative numbers parsed from @a str are considered
206  * invalid, and result in the same error.
207  *
208  * @since New in 1.5.
209  */
210 svn_error_t *
211 svn_revnum_parse(svn_revnum_t *rev,
212  const char *str,
213  const char **endptr);
214 
215 /** Originally intended to be used in printf()-style functions to format
216  * revision numbers. Deprecated due to incompatibilities with language
217  * translation tools (e.g. gettext).
218  *
219  * New code should use a bare "%ld" format specifier for formatting revision
220  * numbers.
221  *
222  * @deprecated Provided for backward compatibility with the 1.0 API.
223  */
224 #define SVN_REVNUM_T_FMT "ld"
225 
226 
227 /** The size of a file in the Subversion FS. */
228 typedef apr_int64_t svn_filesize_t;
229 
230 /** The 'official' invalid file size constant. */
231 #define SVN_INVALID_FILESIZE ((svn_filesize_t) -1)
232 
233 /** In printf()-style functions, format file sizes using this. */
234 #define SVN_FILESIZE_T_FMT APR_INT64_T_FMT
235 
236 #ifndef DOXYGEN_SHOULD_SKIP_THIS
237 /* Parse a base-10 numeric string into a 64-bit unsigned numeric value. */
238 /* NOTE: Private. For use by Subversion's own code only. See issue #1644. */
239 /* FIXME: APR should supply a function to do this, such as "apr_atoui64". */
240 #define svn__atoui64(X) ((apr_uint64_t) apr_atoi64(X))
241 #endif
242 
243 
244 /** YABT: Yet Another Boolean Type */
245 typedef int svn_boolean_t;
246 
247 #ifndef TRUE
248 /** uhh... true */
249 #define TRUE 1
250 #endif /* TRUE */
251 
252 #ifndef FALSE
253 /** uhh... false */
254 #define FALSE 0
255 #endif /* FALSE */
256 
257 
258 /** An enum to indicate whether recursion is needed. */
260 {
261  svn_nonrecursive = 1,
262  svn_recursive
263 };
264 
265 /** The concept of depth for directories.
266  *
267  * @note This is similar to, but not exactly the same as, the WebDAV
268  * and LDAP concepts of depth.
269  *
270  * @since New in 1.5.
271  */
272 typedef enum
273 {
274  /* The order of these depths is important: the higher the number,
275  the deeper it descends. This allows us to compare two depths
276  numerically to decide which should govern. */
277 
278  /* Depth undetermined or ignored. In some contexts, this means the
279  client should choose an appropriate default depth. The server
280  will generally treat it as @c svn_depth_infinity. */
281  svn_depth_unknown = -2,
282 
283  /* Exclude (i.e., don't descend into) directory D. */
284  /* NOTE: In Subversion 1.5, svn_depth_exclude is *not* supported
285  anywhere in the client-side (libsvn_wc/libsvn_client/etc) code;
286  it is only supported as an argument to set_path functions in the
287  ra and repos reporters. (This will enable future versions of
288  Subversion to run updates, etc, against 1.5 servers with proper
289  svn_depth_exclude behavior, once we get a chance to implement
290  client-side support for svn_depth_exclude.)
291  */
292  svn_depth_exclude = -1,
293 
294  /* Just the named directory D, no entries. Updates will not pull in
295  any files or subdirectories not already present. */
296  svn_depth_empty = 0,
297 
298  /* D + its file children, but not subdirs. Updates will pull in any
299  files not already present, but not subdirectories. */
300  svn_depth_files = 1,
301 
302  /* D + immediate children (D and its entries). Updates will pull in
303  any files or subdirectories not already present; those
304  subdirectories' this_dir entries will have depth-empty. */
305  svn_depth_immediates = 2,
306 
307  /* D + all descendants (full recursion from D). Updates will pull
308  in any files or subdirectories not already present; those
309  subdirectories' this_dir entries will have depth-infinity.
310  Equivalent to the pre-1.5 default update behavior. */
311  svn_depth_infinity = 3
312 
313 } svn_depth_t;
314 
315 
316 /** Return a constant string expressing @a depth as an English word,
317  * e.g., "infinity", "immediates", etc. The string is not localized,
318  * as it may be used for client<->server communications.
319  *
320  * @since New in 1.5.
321  */
322 const char *
324 
325 
326 /** Return the appropriate depth for @a depth_str. @a word is as
327  * returned from svn_depth_to_word(). If @a depth_str does not
328  * represent a recognized depth, return @c svn_depth_unknown.
329  *
330  * @since New in 1.5.
331  */
333 svn_depth_from_word(const char *word);
334 
335 
336 /* Return @c svn_depth_infinity if boolean @a recurse is TRUE, else
337  * return @c svn_depth_files.
338  *
339  * @note New code should never need to use this, it is called only
340  * from pre-depth APIs, for compatibility.
341  *
342  * @since New in 1.5.
343  */
344 #define SVN_DEPTH_INFINITY_OR_FILES(recurse) \
345  ((recurse) ? svn_depth_infinity : svn_depth_files)
346 
347 
348 /* Return @c svn_depth_infinity if boolean @a recurse is TRUE, else
349  * return @c svn_depth_immediates.
350  *
351  * @note New code should never need to use this, it is called only
352  * from pre-depth APIs, for compatibility.
353  *
354  * @since New in 1.5.
355  */
356 #define SVN_DEPTH_INFINITY_OR_IMMEDIATES(recurse) \
357  ((recurse) ? svn_depth_infinity : svn_depth_immediates)
358 
359 
360 /* Return @c svn_depth_infinity if boolean @a recurse is TRUE, else
361  * return @c svn_depth_empty.
362  *
363  * @note New code should never need to use this, it is called only
364  * from pre-depth APIs, for compatibility.
365  *
366  * @since New in 1.5.
367  */
368 #define SVN_DEPTH_INFINITY_OR_EMPTY(recurse) \
369  ((recurse) ? svn_depth_infinity : svn_depth_empty)
370 
371 
372 /* Return a recursion boolean based on @a depth.
373  *
374  * Although much code has been converted to use depth, some code still
375  * takes a recurse boolean. In most cases, it makes sense to treat
376  * unknown or infinite depth as recursive, and any other depth as
377  * non-recursive (which in turn usually translates to @c svn_depth_files).
378  */
379 #define SVN_DEPTH_IS_RECURSIVE(depth) \
380  (((depth) == svn_depth_infinity || (depth) == svn_depth_unknown) \
381  ? TRUE : FALSE)
382 
383 
384 /**
385  * It is sometimes convenient to indicate which parts of an @c svn_dirent_t
386  * object you are actually interested in, so that calculating and sending
387  * the data corresponding to the other fields can be avoided. These values
388  * can be used for that purpose.
389  *
390  * @defgroup svn_dirent_fields Dirent fields
391  * @{
392  */
393 
394 /** An indication that you are interested in the @c kind field */
395 #define SVN_DIRENT_KIND 0x00001
396 
397 /** An indication that you are interested in the @c size field */
398 #define SVN_DIRENT_SIZE 0x00002
399 
400 /** An indication that you are interested in the @c has_props field */
401 #define SVN_DIRENT_HAS_PROPS 0x00004
402 
403 /** An indication that you are interested in the @c created_rev field */
404 #define SVN_DIRENT_CREATED_REV 0x00008
405 
406 /** An indication that you are interested in the @c time field */
407 #define SVN_DIRENT_TIME 0x00010
408 
409 /** An indication that you are interested in the @c last_author field */
410 #define SVN_DIRENT_LAST_AUTHOR 0x00020
411 
412 /** A combination of all the dirent fields */
413 #define SVN_DIRENT_ALL ~((apr_uint32_t ) 0)
414 
415 /** @} */
416 
417 /** A general subversion directory entry. */
418 typedef struct svn_dirent_t
419 {
420  /** node kind */
422 
423  /** length of file text, or 0 for directories */
424  svn_filesize_t size;
425 
426  /** does the node have props? */
427  svn_boolean_t has_props;
428 
429  /** last rev in which this node changed */
430  svn_revnum_t created_rev;
431 
432  /** time of created_rev (mod-time) */
433  apr_time_t time;
434 
435  /** author of created_rev */
436  const char *last_author;
437 
438  /* IMPORTANT: If you extend this struct, check svn_dirent_dup(). */
439 } svn_dirent_t;
440 
441 
442 /** Return a deep copy of @a dirent, allocated in @a pool.
443  *
444  * @since New in 1.4.
445  */
446 svn_dirent_t *
447 svn_dirent_dup(const svn_dirent_t *dirent,
448  apr_pool_t *pool);
449 
450 
451 
452 /** Keyword substitution.
453  *
454  * All the keywords Subversion recognizes.
455  *
456  * Note that there is a better, more general proposal out there, which
457  * would take care of both internationalization issues and custom
458  * keywords (e.g., $NetBSD$). See
459  *
460  * @verbatim
461  http://subversion.tigris.org/servlets/ReadMsg?list=dev&msgNo=8921
462  =====
463  From: "Jonathan M. Manning" <jmanning@alisa-jon.net>
464  To: dev@subversion.tigris.org
465  Date: Fri, 14 Dec 2001 11:56:54 -0500
466  Message-ID: <87970000.1008349014@bdldevel.bl.bdx.com>
467  Subject: Re: keywords @endverbatim
468  *
469  * and Eric Gillespie's support of same:
470  *
471  * @verbatim
472  http://subversion.tigris.org/servlets/ReadMsg?list=dev&msgNo=8757
473  =====
474  From: "Eric Gillespie, Jr." <epg@pretzelnet.org>
475  To: dev@subversion.tigris.org
476  Date: Wed, 12 Dec 2001 09:48:42 -0500
477  Message-ID: <87k7vsebp1.fsf@vger.pretzelnet.org>
478  Subject: Re: Customizable Keywords @endverbatim
479  *
480  * However, it is considerably more complex than the scheme below.
481  * For now we're going with simplicity, hopefully the more general
482  * solution can be done post-1.0.
483  *
484  * @defgroup svn_types_keywords Keyword definitions
485  * @{
486  */
487 
488 /** The maximum size of an expanded or un-expanded keyword. */
489 #define SVN_KEYWORD_MAX_LEN 255
490 
491 /** The most recent revision in which this file was changed. */
492 #define SVN_KEYWORD_REVISION_LONG "LastChangedRevision"
493 
494 /** Short version of LastChangedRevision */
495 #define SVN_KEYWORD_REVISION_SHORT "Rev"
496 
497 /** Medium version of LastChangedRevision, matching the one CVS uses.
498  * @since New in 1.1. */
499 #define SVN_KEYWORD_REVISION_MEDIUM "Revision"
500 
501 /** The most recent date (repository time) when this file was changed. */
502 #define SVN_KEYWORD_DATE_LONG "LastChangedDate"
503 
504 /** Short version of LastChangedDate */
505 #define SVN_KEYWORD_DATE_SHORT "Date"
506 
507 /** Who most recently committed to this file. */
508 #define SVN_KEYWORD_AUTHOR_LONG "LastChangedBy"
509 
510 /** Short version of LastChangedBy */
511 #define SVN_KEYWORD_AUTHOR_SHORT "Author"
512 
513 /** The URL for the head revision of this file. */
514 #define SVN_KEYWORD_URL_LONG "HeadURL"
515 
516 /** Short version of HeadURL */
517 #define SVN_KEYWORD_URL_SHORT "URL"
518 
519 /** A compressed combination of the other four keywords. */
520 #define SVN_KEYWORD_ID "Id"
521 
522 /** A full combination of the first four keywords.
523  * @since New in 1.6. */
524 #define SVN_KEYWORD_HEADER "Header"
525 
526 /** @} */
527 
528 
529 /** All information about a commit.
530  *
531  * @note Objects of this type should always be created using the
532  * svn_create_commit_info() function.
533  *
534  * @since New in 1.3.
535  */
536 typedef struct svn_commit_info_t
537 {
538  /** just-committed revision. */
539  svn_revnum_t revision;
540 
541  /** server-side date of the commit. */
542  const char *date;
543 
544  /** author of the commit. */
545  const char *author;
546 
547  /** error message from post-commit hook, or NULL. */
548  const char *post_commit_err;
549 
551 
552 
553 /**
554  * Allocate an object of type @c svn_commit_info_t in @a pool and
555  * return it.
556  *
557  * The @c revision field of the new struct is set to @c
558  * SVN_INVALID_REVNUM. All other fields are initialized to @c NULL.
559  *
560  * @note Any object of the type @c svn_commit_info_t should
561  * be created using this function.
562  * This is to provide for extending the svn_commit_info_t in
563  * the future.
564  *
565  * @since New in 1.3.
566  */
568 svn_create_commit_info(apr_pool_t *pool);
569 
570 
571 /**
572  * Return a deep copy @a src_commit_info allocated in @a pool.
573  *
574  * @since New in 1.4.
575  */
577 svn_commit_info_dup(const svn_commit_info_t *src_commit_info,
578  apr_pool_t *pool);
579 
580 
581 /**
582  * A structure to represent a path that changed for a log entry.
583  *
584  * @note To allow for extending the @c svn_log_changed_path2_t structure in
585  * future releases, always use svn_log_changed_path2_create() to allocate
586  * the structure.
587  *
588  * @since New in 1.6.
589  */
591 {
592  /** 'A'dd, 'D'elete, 'R'eplace, 'M'odify */
593  char action;
594 
595  /** Source path of copy (if any). */
596  const char *copyfrom_path;
597 
598  /** Source revision of copy (if any). */
599  svn_revnum_t copyfrom_rev;
600 
601  /** The type of the node, may be svn_node_unknown. */
603 
604  /* NOTE: Add new fields at the end to preserve binary compatibility.
605  Also, if you add fields here, you have to update
606  svn_log_changed_path2_dup(). */
608 
609 /**
610  * Returns an @c svn_log_changed_path2_t, allocated in @a pool with all fields
611  * initialized to NULL, None or empty values.
612  *
613  * @note To allow for extending the @c svn_log_changed_path2_t structure in
614  * future releases, this function should always be used to allocate the
615  * structure.
616  *
617  * @since New in 1.6.
618  */
620 svn_log_changed_path2_create(apr_pool_t *pool);
621 
622 /**
623  * Return a deep copy of @a changed_path, allocated in @a pool.
624  *
625  * @since New in 1.6.
626  */
629  apr_pool_t *pool);
630 
631 /**
632  * A structure to represent a path that changed for a log entry. Same as
633  * @c svn_log_changed_path2_t, but without the node kind.
634  *
635  * @deprecated Provided for backward compatibility with the 1.5 API.
636  */
638 {
639  /** 'A'dd, 'D'elete, 'R'eplace, 'M'odify */
640  char action;
641 
642  /** Source path of copy (if any). */
643  const char *copyfrom_path;
644 
645  /** Source revision of copy (if any). */
646  svn_revnum_t copyfrom_rev;
647 
649 
650 
651 /**
652  * Return a deep copy of @a changed_path, allocated in @a pool.
653  *
654  * @since New in 1.3.
655  * @deprecated Provided for backward compatibility with the 1.5 API.
656  */
660  apr_pool_t *pool);
661 
662 /**
663  * A structure to represent all the information about a particular log entry.
664  *
665  * @note To allow for extending the @c svn_log_entry_t structure in future
666  * releases, always use svn_log_entry_create() to allocate the structure.
667  *
668  * @since New in 1.5.
669  */
670 typedef struct svn_log_entry_t
671 {
672  /** A hash containing as keys every path committed in @a revision; the
673  * values are (@c svn_log_changed_path_t *) stuctures.
674  *
675  * The subversion core libraries will always set this field to the same
676  * value as changed_paths2 for compatibity reasons.
677  *
678  * @deprecated Provided for backward compatibility with the 1.5 API.
679  */
680  apr_hash_t *changed_paths;
681 
682  /** The revision of the commit. */
683  svn_revnum_t revision;
684 
685  /** The hash of requested revision properties, which may be NULL if it
686  * would contain no revprops. */
687  apr_hash_t *revprops;
688 
689  /**
690  * Whether or not this message has children.
691  *
692  * When a log operation requests additional merge information, extra log
693  * entries may be returned as a result of this entry. The new entries, are
694  * considered children of the original entry, and will follow it. When
695  * the HAS_CHILDREN flag is set, the receiver should increment its stack
696  * depth, and wait until an entry is provided with SVN_INVALID_REVNUM which
697  * indicates the end of the children.
698  *
699  * For log operations which do not request additional merge information, the
700  * HAS_CHILDREN flag is always FALSE.
701  *
702  * For more information see:
703  * http://subversion.tigris.org/merge-tracking/design.html#commutative-reporting
704  */
705  svn_boolean_t has_children;
706 
707  /** A hash containing as keys every path committed in @a revision; the
708  * values are (@c svn_log_changed_path2_t *) stuctures.
709  *
710  * If this value is not @c NULL, it MUST have the same value as
711  * changed_paths or svn_log_entry_dup() will not create an identical copy.
712  *
713  * The subversion core libraries will always set this field to the same
714  * value as changed_paths for compatibity with users assuming an older
715  * version.
716  *
717  * @since New in 1.6.
718  */
719  apr_hash_t *changed_paths2;
720 
721  /* NOTE: Add new fields at the end to preserve binary compatibility.
722  Also, if you add fields here, you have to update
723  svn_log_entry_dup(). */
725 
726 /**
727  * Returns an @c svn_log_entry_t, allocated in @a pool with all fields
728  * initialized to NULL values.
729  *
730  * @note To allow for extending the @c svn_log_entry_t structure in future
731  * releases, this function should always be used to allocate the structure.
732  *
733  * @since New in 1.5.
734  */
736 svn_log_entry_create(apr_pool_t *pool);
737 
738 /** Return a deep copy of @a log_entry, allocated in @a pool.
739  *
740  * The resulting svn_log_entry_t has @c changed_paths set to the same
741  * value as @c changed_path2. @c changed_paths will be @c NULL if
742  * @c changed_paths2 was @c NULL.
743  *
744  * @since New in 1.6.
745  */
747 svn_log_entry_dup(svn_log_entry_t *log_entry, apr_pool_t *pool);
748 
749 /** The callback invoked by log message loopers, such as
750  * @c svn_ra_plugin_t.get_log() and svn_repos_get_logs().
751  *
752  * This function is invoked once on each log message, in the order
753  * determined by the caller (see above-mentioned functions).
754  *
755  * @a baton is what you think it is, and @a log_entry contains relevent
756  * information for the log message. Any of @a log_entry->author,
757  * @a log_entry->date, or @a log_entry->message may be @c NULL.
758  *
759  * If @a log_entry->date is neither NULL nor the empty string, it was
760  * generated by svn_time_to_cstring() and can be converted to
761  * @c apr_time_t with svn_time_from_cstring().
762  *
763  * If @a log_entry->changed_paths is non-@c NULL, then it contains as keys
764  * every path committed in @a log_entry->revision; the values are
765  * (@c svn_log_changed_path_t *) structures.
766  *
767  * If @a log_entry->has_children is @c TRUE, the message will be followed
768  * immediately by any number of merged revisions (child messages), which are
769  * terminated by an invocation with SVN_INVALID_REVNUM. This usage may
770  * be recursive.
771  *
772  * Use @a pool for temporary allocation. If the caller is iterating
773  * over log messages, invoking this receiver on each, we recommend the
774  * standard pool loop recipe: create a subpool, pass it as @a pool to
775  * each call, clear it after each iteration, destroy it after the loop
776  * is done. (For allocation that must last beyond the lifetime of a
777  * given receiver call, use a pool in @a baton.)
778  *
779  * @since New in 1.5.
780  */
781 
782 typedef svn_error_t *(*svn_log_entry_receiver_t)
783  (void *baton,
784  svn_log_entry_t *log_entry,
785  apr_pool_t *pool);
786 
787 /**
788  * Similar to @c svn_log_entry_receiver_t, except this uses separate
789  * parameters for each part of the log entry.
790  *
791  * @deprecated Provided for backward compatibility with the 1.4 API.
792  */
793 typedef svn_error_t *(*svn_log_message_receiver_t)
794  (void *baton,
795  apr_hash_t *changed_paths,
796  svn_revnum_t revision,
797  const char *author,
798  const char *date, /* use svn_time_from_cstring() if need apr_time_t */
799  const char *message,
800  apr_pool_t *pool);
801 
802 
803 /** Callback function type for commits.
804  *
805  * When a commit succeeds, an instance of this is invoked with the
806  * @a commit_info, along with the @a baton closure.
807  * @a pool can be used for temporary allocations.
808  *
809  * @since New in 1.4.
810  */
811 typedef svn_error_t *(*svn_commit_callback2_t)
812  (const svn_commit_info_t *commit_info,
813  void *baton,
814  apr_pool_t *pool);
815 
816 /** Same as @c svn_commit_callback2_t, but uses individual
817  * data elements instead of the @c svn_commit_info_t structure
818  *
819  * @deprecated Provided for backward compatibility with the 1.3 API.
820  */
821 typedef svn_error_t *(*svn_commit_callback_t)
822  (svn_revnum_t new_revision,
823  const char *date,
824  const char *author,
825  void *baton);
826 
827 
828 /** A buffer size that may be used when processing a stream of data.
829  *
830  * @note We don't use this constant any longer, since it is considered to be
831  * unnecessarily large.
832  *
833  * @deprecated Provided for backwards compatibility with the 1.3 API.
834  */
835 #define SVN_STREAM_CHUNK_SIZE 102400
836 
837 #ifndef DOXYGEN_SHOULD_SKIP_THIS
838 /*
839  * The maximum amount we (ideally) hold in memory at a time when
840  * processing a stream of data.
841  *
842  * For example, when copying data from one stream to another, do it in
843  * blocks of this size.
844  *
845  * NOTE: This is an internal macro, put here for convenience.
846  * No public API may depend on the particular value of this macro.
847  */
848 #define SVN__STREAM_CHUNK_SIZE 16384
849 #endif
850 
851 /** The maximum amount we can ever hold in memory. */
852 /* FIXME: Should this be the same as SVN_STREAM_CHUNK_SIZE? */
853 #define SVN_MAX_OBJECT_SIZE (((apr_size_t) -1) / 2)
854 
855 
856 
857 /* ### Note: despite being about mime-TYPES, these probably don't
858  * ### belong in svn_types.h. However, no other header is more
859  * ### appropriate, and didn't feel like creating svn_validate.h for
860  * ### so little.
861  */
862 
863 /** Validate @a mime_type.
864  *
865  * If @a mime_type does not contain a "/", or ends with non-alphanumeric
866  * data, return @c SVN_ERR_BAD_MIME_TYPE, else return success.
867  *
868  * Use @a pool only to find error allocation.
869  *
870  * Goal: to match both "foo/bar" and "foo/bar; charset=blah", without
871  * being too strict about it, but to disallow mime types that have
872  * quotes, newlines, or other garbage on the end, such as might be
873  * unsafe in an HTTP header.
874  */
875 svn_error_t *
876 svn_mime_type_validate(const char *mime_type,
877  apr_pool_t *pool);
878 
879 
880 /** Return FALSE iff @a mime_type is a textual type.
881  *
882  * All mime types that start with "text/" are textual, plus some special
883  * cases (for example, "image/x-xbitmap").
884  */
885 svn_boolean_t
886 svn_mime_type_is_binary(const char *mime_type);
887 
888 
889 
890 /** A user defined callback that subversion will call with a user defined
891  * baton to see if the current operation should be continued. If the operation
892  * should continue, the function should return @c SVN_NO_ERROR, if not, it
893  * should return @c SVN_ERR_CANCELLED.
894  */
895 typedef svn_error_t *(*svn_cancel_func_t)(void *cancel_baton);
896 
897 
898 
899 /**
900  * A lock object, for client & server to share.
901  *
902  * A lock represents the exclusive right to add, delete, or modify a
903  * path. A lock is created in a repository, wholly controlled by the
904  * repository. A "lock-token" is the lock's UUID, and can be used to
905  * learn more about a lock's fields, and or/make use of the lock.
906  * Because a lock is immutable, a client is free to not only cache the
907  * lock-token, but the lock's fields too, for convenience.
908  *
909  * Note that the 'is_dav_comment' field is wholly ignored by every
910  * library except for mod_dav_svn. The field isn't even marshalled
911  * over the network to the client. Assuming lock structures are
912  * created with apr_pcalloc(), a default value of 0 is universally safe.
913  *
914  * @note in the current implementation, only files are lockable.
915  *
916  * @since New in 1.2.
917  */
918 typedef struct svn_lock_t
919 {
920  const char *path; /**< the path this lock applies to */
921  const char *token; /**< unique URI representing lock */
922  const char *owner; /**< the username which owns the lock */
923  const char *comment; /**< (optional) description of lock */
924  svn_boolean_t is_dav_comment; /**< was comment made by generic DAV client? */
925  apr_time_t creation_date; /**< when lock was made */
926  apr_time_t expiration_date; /**< (optional) when lock will expire;
927  If value is 0, lock will never expire. */
928 } svn_lock_t;
929 
930 /**
931  * Returns an @c svn_lock_t, allocated in @a pool with all fields initialized
932  * to NULL values.
933  *
934  * @note To allow for extending the @c svn_lock_t structure in the future
935  * releases, this function should always be used to allocate the structure.
936  *
937  * @since New in 1.2.
938  */
939 svn_lock_t *
940 svn_lock_create(apr_pool_t *pool);
941 
942 /**
943  * Return a deep copy of @a lock, allocated in @a pool.
944  *
945  * @since New in 1.2.
946  */
947 svn_lock_t *
948 svn_lock_dup(const svn_lock_t *lock, apr_pool_t *pool);
949 
950 /**
951  * Return a formatted Universal Unique IDentifier (UUID) string.
952  *
953  * @since New in 1.4.
954  */
955 const char *
956 svn_uuid_generate(apr_pool_t *pool);
957 
958 /**
959  * Mergeinfo representing a merge of a range of revisions.
960  *
961  * @since New in 1.5
962  */
963 typedef struct svn_merge_range_t
964 {
965  /**
966  * If the 'start' field is less than the 'end' field then 'start' is
967  * exclusive and 'end' inclusive of the range described. This is termed
968  * a forward merge range. If 'start' is greater than 'end' then the
969  * opposite is true. This is termed a reverse merge range. If 'start'
970  * equals 'end' the meaning of the range is not defined.
971  */
972  svn_revnum_t start;
973  svn_revnum_t end;
974 
975  /**
976  * Whether this merge range should be inherited by treewise
977  * descendants of the path to which the range applies. */
978  svn_boolean_t inheritable;
980 
981 /**
982  * Return a copy of @a range, allocated in @a pool.
983  *
984  * @since New in 1.5.
985  */
987 svn_merge_range_dup(svn_merge_range_t *range, apr_pool_t *pool);
988 
989 /**
990  * Returns true if the changeset committed in revision @a rev is one
991  * of the changesets in the range @a range.
992  *
993  * @since New in 1.5.
994  */
995 svn_boolean_t
996 svn_merge_range_contains_rev(svn_merge_range_t *range, svn_revnum_t rev);
997 
998 
999 
1000 /** @defgroup node_location_seg_reporting Node location segment reporting.
1001  * @{ */
1002 
1003 /**
1004  * A representation of a segment of a object's version history with an
1005  * emphasis on the object's location in the repository as of various
1006  * revisions.
1007  *
1008  * @since New in 1.5.
1009  */
1011 {
1012  /** The beginning (oldest) and ending (youngest) revisions for this
1013  segment. */
1014  svn_revnum_t range_start;
1015  svn_revnum_t range_end;
1016 
1017  /** The absolute (sans leading slash) path for this segment. May be
1018  NULL to indicate gaps in an object's history. */
1019  const char *path;
1020 
1022 
1023 
1024 /**
1025  * A callback invoked by generators of @c svn_location_segment_t
1026  * objects, used to report information about a versioned object's
1027  * history in terms of its location in the repository filesystem over
1028  * time.
1029  */
1030 typedef svn_error_t *(*svn_location_segment_receiver_t)
1032  void *baton,
1033  apr_pool_t *pool);
1034 
1035 
1036 /**
1037  * Return a deep copy of @a segment, allocated in @a pool.
1038  *
1039  * @since New in 1.5.
1040  */
1043  apr_pool_t *pool);
1044 /** @} */
1045 
1046 
1047 #ifdef __cplusplus
1048 }
1049 #endif /* __cplusplus */
1050 
1051 
1052 /*
1053  * Everybody and their brother needs to deal with svn_error_t, the error
1054  * codes, and whatever else. While they *should* go and include svn_error.h
1055  * in order to do that... bah. Let's just help everybody out and include
1056  * that header whenever somebody grabs svn_types.h.
1057  *
1058  * Note that we do this at the END of this header so that its contents
1059  * are available to svn_error.h (our guards will prevent the circular
1060  * include). We also need to do the include *outside* of the cplusplus
1061  * guard.
1062  */
1063 #include "svn_error.h"
1064 
1065 
1066 #endif /* SVN_TYPES_H */