Main Page | Modules | Data Structures | File List | Data Fields | Globals | Related Pages

svn_ra.h

Go to the documentation of this file.
00001 /**
00002  * @copyright
00003  * ====================================================================
00004  * Copyright (c) 2000-2004 CollabNet.  All rights reserved.
00005  *
00006  * This software is licensed as described in the file COPYING, which
00007  * you should have received as part of this distribution.  The terms
00008  * are also available at http://subversion.tigris.org/license-1.html.
00009  * If newer versions of this license are posted there, you may use a
00010  * newer version instead, at your option.
00011  *
00012  * This software consists of voluntary contributions made by many
00013  * individuals.  For exact contribution history, see the revision
00014  * history and logs, available at http://subversion.tigris.org/.
00015  * ====================================================================
00016  * @endcopyright
00017  *
00018  * @file svn_ra.h
00019  * @brief Repository Access
00020  */
00021 
00022 
00023 
00024 
00025 #ifndef SVN_RA_H
00026 #define SVN_RA_H
00027 
00028 #include <apr_pools.h>
00029 #include <apr_tables.h>
00030 
00031 #include "svn_error.h"
00032 #include "svn_delta.h"
00033 #include "svn_auth.h"
00034 
00035 #ifdef __cplusplus
00036 extern "C" {
00037 #endif /* __cplusplus */
00038 
00039 
00040 
00041 /* Misc. declarations */
00042 
00043 /**
00044  * Get libsvn_ra version information.
00045  *
00046  * @since New in 1.1.
00047  */
00048 const svn_version_t *svn_ra_version (void);
00049 
00050 
00051 /** This is a function type which allows the RA layer to fetch working
00052  * copy (WC) properties.
00053  *
00054  * The @a baton is provided along with the function pointer and should
00055  * be passed back in. This will be the @a callback_baton or the 
00056  * @a close_baton as appropriate.
00057  *
00058  * @a path is relative to the "root" of the session, defined by the 
00059  * @a repos_url passed to the @c RA->open() vtable call.
00060  *
00061  * @a name is the name of the property to fetch. If the property is present,
00062  * then it is returned in @a value. Otherwise, @a *value is set to @c NULL.
00063  */
00064 typedef svn_error_t *(*svn_ra_get_wc_prop_func_t) (void *baton,
00065                                                    const char *relpath,
00066                                                    const char *name,
00067                                                    const svn_string_t **value,
00068                                                    apr_pool_t *pool);
00069 
00070 /** This is a function type which allows the RA layer to store new
00071  * working copy properties during update-like operations.  See the
00072  * comments for @c svn_ra_get_wc_prop_func_t for @a baton, @a path, and 
00073  * @a name. The @a value is the value that will be stored for the property; 
00074  * a null @a value means the property will be deleted.
00075  */
00076 typedef svn_error_t *(*svn_ra_set_wc_prop_func_t) (void *baton,
00077                                                    const char *path,
00078                                                    const char *name,
00079                                                    const svn_string_t *value,
00080                                                    apr_pool_t *pool);
00081 
00082 /** This is a function type which allows the RA layer to store new
00083  * working copy properties as part of a commit.  See the comments for
00084  * @c svn_ra_get_wc_prop_func_t for @a baton, @a path, and @a name.  
00085  * The @a value is the value that will be stored for the property; a 
00086  * @c NULL @a value means the property will be deleted.
00087  *
00088  * Note that this might not actually store the new property before
00089  * returning, but instead schedule it to be changed as part of
00090  * post-commit processing (in which case a successful commit means the
00091  * properties got written).  Thus, during the commit, it is possible
00092  * to invoke this function to set a new value for a wc prop, then read
00093  * the wc prop back from the working copy and get the *old* value.
00094  * Callers beware.
00095  */
00096 typedef svn_error_t *(*svn_ra_push_wc_prop_func_t) (void *baton,
00097                                                     const char *path,
00098                                                     const char *name,
00099                                                     const svn_string_t *value,
00100                                                     apr_pool_t *pool);
00101 
00102 /** This is a function type which allows the RA layer to invalidate
00103  * (i.e., remove) wcprops.  See the documentation for
00104  * @c svn_ra_get_wc_prop_func_t for @a baton, @a path, and @a name.
00105  *
00106  * Unlike @c svn_ra_push_wc_prop_func_t, this has immediate effect.  If
00107  * it returns success, the wcprops have been removed.
00108  */
00109 typedef svn_error_t *(*svn_ra_invalidate_wc_props_func_t) (void *baton,
00110                                                            const char *path,
00111                                                            const char *name,
00112                                                            apr_pool_t *pool);
00113 
00114 
00115 /** A function type for retrieving the youngest revision from a repos. */
00116 typedef svn_error_t *(*svn_ra_get_latest_revnum_func_t) 
00117        (void *session_baton,
00118         svn_revnum_t *latest_revnum);
00119 
00120 /**
00121  * A callback function type for use in @c get_file_revs.
00122  * @a baton is provided by the caller, @a path is the pathname of the file
00123  * in revision @a rev and @a rev_props are the revision properties.
00124  * If @a delta_handler and @a delta_baton are non-NULL, they may be set to a
00125  * handler/baton which will be called with the delta between the previous
00126  * revision and this one after the return of this callback.  They may be
00127  * left as NULL/NULL.
00128  * @a prop_diffs is an array of svn_prop_t elements indicating the property
00129  * delta for this and the previous revision.
00130  * @a pool may be used for temporary allocations, but you can't rely
00131  * on objects allocated to live outside of this particular call and the
00132  * immediately following calls to @a *delta_handler, if any.
00133  *
00134  * @since New in 1.1.
00135  */
00136 typedef svn_error_t *(*svn_ra_file_rev_handler_t)
00137        (void *baton,
00138         const char *path,
00139         svn_revnum_t rev,
00140         apr_hash_t *rev_props,
00141         svn_txdelta_window_handler_t *delta_handler,
00142         void **delta_baton,
00143         apr_array_header_t *prop_diffs,
00144         apr_pool_t *pool);
00145 
00146 /** 
00147  * Callback function type for locking and unlocking actions.
00148  * 
00149  * @since New in 1.2.
00150  *
00151  * @a do_lock is TRUE when locking @a path, and FALSE
00152  * otherwise.
00153  * 
00154  * @a lock is a lock for @a path or null if @a do_lock is false or @a ra_err is
00155  * non-null.
00156  *
00157  * @a ra_err is NULL unless the ra layer encounters a locking related
00158  * error which it passes back for notification purposes.  The caller
00159  * is responsible for clearing @a ra_err after the callback is run.
00160  *
00161  * @a baton is a closure object; it should be provided by the
00162  * implementation, and passed by the caller.  @a pool may be used for
00163  * temporary allocation.
00164  */
00165 typedef svn_error_t *(*svn_ra_lock_callback_t) (void *baton,
00166                                                 const char *path,
00167                                                 svn_boolean_t do_lock,
00168                                                 const svn_lock_t *lock,
00169                                                 svn_error_t *ra_err,
00170                                                 apr_pool_t *pool);
00171 
00172 /**
00173  * Callback function type for progress notification.
00174  *
00175  * @a progress is the number of bytes already transferred, @a total is
00176  * the total number of bytes to transfer or -1 if it's not known, @a
00177  * baton is the callback baton.
00178  *
00179  * @since New in 1.3.
00180  */
00181 typedef void (*svn_ra_progress_notify_func_t) (apr_off_t progress,
00182                                                apr_off_t total,
00183                                                void *baton,
00184                                                apr_pool_t *pool);
00185 
00186 
00187 /**
00188  * The update Reporter.
00189  *
00190  * A vtable structure which allows a working copy to describe a subset
00191  * (or possibly all) of its working-copy to an RA layer, for the
00192  * purposes of an update, switch, status, or diff operation.
00193  *
00194  * Paths for report calls are relative to the target (not the anchor)
00195  * of the operation.  Report calls must be made in depth-first order:
00196  * parents before children, all children of a parent before any
00197  * siblings of the parent.  The first report call must be a set_path
00198  * with a @a path argument of "" and a valid revision.  (If the target
00199  * of the operation is locally deleted or missing, use the anchor's
00200  * revision.)  If the target of the operation is deleted or switched
00201  * relative to the anchor, follow up the initial set_path call with a
00202  * link_path or delete_path call with a @a path argument of "" to
00203  * indicate that.  In no other case may there be two report
00204  * descriptions for the same path.  If the target of the operation is
00205  * a locally added file or directory (which previously did not exist),
00206  * it may be reported as having revision 0 or as having the parent
00207  * directory's revision.
00208  *
00209  * @since New in 1.2.
00210  */
00211 typedef struct svn_ra_reporter2_t
00212 {
00213   /** Describe a working copy @a path as being at a particular @a revision.  
00214    *
00215    * If @a start_empty is set and @a path is a directory, the
00216    * implementor should assume the directory has no entries or props.
00217    *
00218    * This will *override* any previous set_path() calls made on parent
00219    * paths.  @a path is relative to the URL specified in @c RA->open().
00220    *
00221    * If @a lock_token is non-NULL, it is the lock token for @a path in the WC.
00222    * 
00223    * All temporary allocations are done in @a pool.
00224    */
00225   svn_error_t *(*set_path) (void *report_baton,
00226                             const char *path,
00227                             svn_revnum_t revision,
00228                             svn_boolean_t start_empty,
00229                             const char *lock_token,
00230                             apr_pool_t *pool);
00231 
00232   /** Describing a working copy @a path as missing.
00233    *
00234    * All temporary allocations are done in @a pool.
00235    */
00236   svn_error_t *(*delete_path) (void *report_baton,
00237                                const char *path,
00238                                apr_pool_t *pool);
00239     
00240   /** Like set_path(), but differs in that @a path in the working copy
00241    * (relative to the root of the report driver) isn't a reflection of
00242    * @a path in the repository (relative to the URL specified when
00243    * opening the RA layer), but is instead a reflection of a different
00244    * repository @a url at @a revision.
00245    *
00246    * If @a start_empty is set and @a path is a directory,
00247    * the implementor should assume the directory has no entries or props.
00248    *
00249    * If @a lock_token is non-NULL, it is the lock token for @a path in the WC.
00250    * 
00251    * All temporary allocations are done in @a pool.
00252    */
00253   svn_error_t *(*link_path) (void *report_baton,
00254                              const char *path,
00255                              const char *url,
00256                              svn_revnum_t revision,
00257                              svn_boolean_t start_empty,
00258                              const char *lock_token,
00259                              apr_pool_t *pool);
00260 
00261   /** WC calls this when the state report is finished; any directories
00262    * or files not explicitly `set' are assumed to be at the
00263    * baseline revision originally passed into do_update().  No other
00264    * reporting functions, including abort_report, should be called after
00265    * calling this function.
00266    */
00267   svn_error_t *(*finish_report) (void *report_baton,
00268                                  apr_pool_t *pool);
00269 
00270   /** If an error occurs during a report, this routine should cause the
00271    * filesystem transaction to be aborted & cleaned up.  No other reporting
00272    * functions should be called after calling this function.
00273    */
00274   svn_error_t *(*abort_report) (void *report_baton,
00275                                 apr_pool_t *pool);
00276 
00277 } svn_ra_reporter2_t;
00278 
00279 /**
00280  * Similar to @c svn_ra_reporter2_t, but without support for lock tokens.
00281  *
00282  * @deprecated Provided for backward compatibility with the 1.1 API.
00283  */
00284 typedef struct svn_ra_reporter_t
00285 {
00286   /** Similar to the corresponding field in @c svn_ra_reporter2_t, but
00287    * with @a lock_token always set to NULL. */
00288   svn_error_t *(*set_path) (void *report_baton,
00289                             const char *path,
00290                             svn_revnum_t revision,
00291                             svn_boolean_t start_empty,
00292                             apr_pool_t *pool);
00293 
00294   /** Same as the corresponding field in @c svn_ra_reporter2_t. */
00295   svn_error_t *(*delete_path) (void *report_baton,
00296                                const char *path,
00297                                apr_pool_t *pool);
00298     
00299   /** Similar to the corresponding field in @c svn_ra_reporter2_t, but
00300    * with @a lock_token always set to NULL. */
00301   svn_error_t *(*link_path) (void *report_baton,
00302                              const char *path,
00303                              const char *url,
00304                              svn_revnum_t revision,
00305                              svn_boolean_t start_empty,
00306                              apr_pool_t *pool);
00307 
00308   /** Same as the corresponding field in @c svn_ra_reporter2_t. */
00309   svn_error_t *(*finish_report) (void *report_baton,
00310                                  apr_pool_t *pool);
00311 
00312   /** Same as the corresponding field in @c svn_ra_reporter2_t. */
00313   svn_error_t *(*abort_report) (void *report_baton,
00314                                 apr_pool_t *pool);
00315 } svn_ra_reporter_t;
00316 
00317 
00318 /** A collection of callbacks implemented by libsvn_client which allows
00319  * an RA layer to "pull" information from the client application, or
00320  * possibly store information.  libsvn_client passes this vtable to
00321  * @c RA->open().  
00322  *
00323  * Each routine takes a @a callback_baton originally provided with the
00324  * vtable.
00325  *
00326  * Clients must use svn_ra_create_callbacks() to allocate and
00327  * initialize this structure.
00328  *
00329  * @since New in 1.3.
00330  */
00331 typedef struct svn_ra_callbacks2_t
00332 {
00333   /** Open a unique temporary file for writing in the working copy.
00334    * This file will be automatically deleted when @a fp is closed.
00335    */
00336   svn_error_t *(*open_tmp_file) (apr_file_t **fp,
00337                                  void *callback_baton,
00338                                  apr_pool_t *pool);
00339 
00340   /** An authentication baton, created by the application, which is
00341    * capable of retrieving all known types of credentials.
00342    */
00343   svn_auth_baton_t *auth_baton;
00344 
00345   /*** The following items may be set to NULL to disallow the RA layer
00346        to perform the respective operations of the vtable functions.
00347        Perhaps WC props are not defined or are in invalid for this
00348        session, or perhaps the commit operation this RA session will
00349        perform is a server-side only one that shouldn't do post-commit
00350        processing on a working copy path.  ***/
00351 
00352   /** Fetch working copy properties.
00353    *
00354    *<pre> ### we might have a problem if the RA layer ever wants a property
00355    * ### that corresponds to a different revision of the file than
00356    * ### what is in the WC. we'll cross that bridge one day...</pre>
00357    */
00358   svn_ra_get_wc_prop_func_t get_wc_prop;
00359 
00360   /** Immediately set new values for working copy properties. */
00361   svn_ra_set_wc_prop_func_t set_wc_prop;
00362 
00363   /** Schedule new values for working copy properties. */
00364   svn_ra_push_wc_prop_func_t push_wc_prop;
00365 
00366   /** Invalidate working copy properties. */
00367   svn_ra_invalidate_wc_props_func_t invalidate_wc_props;
00368 
00369   /** Notification callback used for progress information.
00370    * May be NULL if not used.
00371    */
00372   svn_ra_progress_notify_func_t progress_func;
00373 
00374   /** Notification callback baton, used with progress_func. */
00375   void *progress_baton;
00376 } svn_ra_callbacks2_t;
00377 
00378 /** Similar to svn_ra_callbacks2_t, except that the progress
00379  * notification function and baton is missing.
00380  *
00381  * @deprecated Provided for backward compatibility with the 1.2 API.
00382  */
00383 typedef struct svn_ra_callbacks_t
00384 {
00385   svn_error_t *(*open_tmp_file) (apr_file_t **fp,
00386                                  void *callback_baton,
00387                                  apr_pool_t *pool);
00388   
00389   svn_auth_baton_t *auth_baton;
00390 
00391   svn_ra_get_wc_prop_func_t get_wc_prop;
00392 
00393   svn_ra_set_wc_prop_func_t set_wc_prop;
00394 
00395   svn_ra_push_wc_prop_func_t push_wc_prop;
00396 
00397   svn_ra_invalidate_wc_props_func_t invalidate_wc_props;
00398 
00399 } svn_ra_callbacks_t;
00400 
00401 
00402 
00403 /*----------------------------------------------------------------------*/
00404 
00405 /* Public Interfaces. */
00406 
00407 /**
00408  * Initialize the RA library.  This function must be called before using
00409  * any function in this header, except the deprecated APIs based on
00410  * @c svn_ra_plugin_t, or svn_ra_version().  This function must not be called
00411  * simultaneously in multiple threads.  @a pool must live
00412  * longer than any open RA sessions.
00413  *
00414  * @since New in 1.2.
00415  */
00416 svn_error_t *
00417 svn_ra_initialize (apr_pool_t *pool);
00418 
00419 /** Initialize a callback structure.
00420 * Set @a *callbacks to a ra callbacks object, allocated in @a pool.
00421 *
00422 * Clients must use this function to allocate and initialize @c
00423 * svn_ra_callbacks2_t structures.
00424 *
00425 * @since New in 1.3.
00426 */
00427 svn_error_t *
00428 svn_ra_create_callbacks (svn_ra_callbacks2_t **callbacks,
00429                          apr_pool_t *pool);
00430 
00431 /**
00432  * A repository access session.  This object is used to perform requests
00433  * to a repository, identified by an URL.
00434  *
00435  * @since New in 1.2.
00436  */
00437 typedef struct svn_ra_session_t svn_ra_session_t;
00438 
00439 /**
00440  * Open a repository session to @a repos_URL.  Return an opaque object
00441  * representing this session in @a *session_p, allocated in @a pool.
00442  *
00443  * @a callbacks/@a callback_baton is a table of callbacks provided by the
00444  * client; see @c svn_ra_callbacks2_t.
00445  *
00446  * @a config is a hash mapping <tt>const char *</tt> keys to 
00447  * @c svn_config_t * values.  For example, the @c svn_config_t for the 
00448  * "~/.subversion/config" file is under the key "config".
00449  *
00450  * All RA requests require a session; they will continue to
00451  * use @a pool for memory allocation.
00452  *
00453  * @see svn_client_open_ra_session().
00454  *
00455  * @since New in 1.3.
00456  */
00457 svn_error_t *svn_ra_open2 (svn_ra_session_t **session_p,
00458                           const char *repos_URL,
00459                           const svn_ra_callbacks2_t *callbacks,
00460                           void *callback_baton,
00461                           apr_hash_t *config,
00462                           apr_pool_t *pool);
00463 
00464 /**
00465  * @see svn_ra_open2().
00466  * @since New in 1.2.
00467  * @deprecated Provided for backward compatibility with the 1.2 API.
00468  */
00469 svn_error_t *svn_ra_open (svn_ra_session_t **session_p,
00470                           const char *repos_URL,
00471                           const svn_ra_callbacks_t *callbacks,
00472                           void *callback_baton,
00473                           apr_hash_t *config,
00474                           apr_pool_t *pool);
00475 
00476 /**
00477  * Get the latest revision number from the repository of @a session.
00478  *
00479  * Use @a pool for memory allocation.
00480  *
00481  * @since New in 1.2.
00482  */
00483 svn_error_t *svn_ra_get_latest_revnum (svn_ra_session_t *session,
00484                                        svn_revnum_t *latest_revnum,
00485                                        apr_pool_t *pool);
00486 
00487 /**
00488  * Get the latest revision number at time @a tm in the repository of
00489  * @a session.
00490  *
00491  * Use @a pool for memory allocation.
00492  *
00493  * @since New in 1.2.
00494  */
00495 svn_error_t *svn_ra_get_dated_revision (svn_ra_session_t *session,
00496                                         svn_revnum_t *revision,
00497                                         apr_time_t tm,
00498                                         apr_pool_t *pool);
00499 
00500 /**
00501  * Set the property @a name to @a value on revision @a rev in the repository
00502  * of @a session.
00503  *
00504  * If @a value is @c NULL, delete the named revision property.
00505  *
00506  * Please note that properties attached to revisions are @em unversioned.
00507  *
00508  * Use @a pool for memory allocation.
00509  *
00510  * @since New in 1.2.
00511  */
00512 svn_error_t *svn_ra_change_rev_prop (svn_ra_session_t *session,
00513                                      svn_revnum_t rev,
00514                                      const char *name,
00515                                      const svn_string_t *value,
00516                                      apr_pool_t *pool);
00517 
00518 /**
00519  * Set @a *props to the list of unversioned properties attached to revision
00520  * @a rev in the repository of @a session.  The hash maps
00521  * (<tt>const char *</tt>) names to (<tt>@c svn_string_t *</tt>) values.
00522  *
00523  * Use @a pool for memory allocation.
00524  *
00525  * @since New in 1.2.
00526  */
00527 svn_error_t *svn_ra_rev_proplist (svn_ra_session_t *session,
00528                                   svn_revnum_t rev,
00529                                   apr_hash_t **props,
00530                                   apr_pool_t *pool);
00531 
00532 /**
00533  * Set @a *value to the value of unversioned property @a name attached to
00534  * revision @a rev in the repository of @a session.  If @a rev has no
00535  * property by that name, set @a *value to @c NULL.
00536  *
00537  * Use @a pool for memory allocation.
00538  *
00539  * @since New in 1.2.
00540  */
00541 svn_error_t *svn_ra_rev_prop (svn_ra_session_t *session,
00542                               svn_revnum_t rev,
00543                               const char *name,
00544                               svn_string_t **value,
00545                               apr_pool_t *pool);
00546 
00547 /**
00548  * Set @a *editor and @a *edit_baton to an editor for committing changes
00549  * to the repository of @a session, using @a log_msg as the log message.  The
00550  * revisions being committed against are passed to the editor
00551  * functions, starting with the rev argument to @c open_root.  The path
00552  * root of the commit is in the @a session's URL.
00553  *
00554  * Before @c close_edit returns, but after the commit has succeeded,
00555  * it will invoke @a callback with the new revision number, the
00556  * commit date (as a <tt>const char *</tt>), commit author (as a
00557  * <tt>const char *</tt>), and @a callback_baton as arguments.  If
00558  * @a callback returns an error, that error will be returned from @c
00559  * close_edit, otherwise @c close_edit will return successfully
00560  * (unless it encountered an error before invoking @a callback).
00561  *
00562  * The callback will not be called if the commit was a no-op
00563  * (i.e. nothing was committed);
00564  *
00565  * @a lock_tokens, if non-NULL, is a hash mapping <tt>const char
00566  * *</tt> paths (relative to the URL of @a session_baton) to <tt>
00567  * const char *</tt> lock tokens.  The server checks that the
00568  * correct token is provided for each committed, locked path.  @a lock_tokens
00569  * must live during the whole commit operation.
00570  *
00571  * If @a keep_locks is @c TRUE, then do not release locks on
00572  * committed objects.  Else, automatically release such locks.
00573  *
00574  * The caller may not perform any RA operations using @a session before
00575  * finishing the edit.
00576  * 
00577  * Use @a pool for memory allocation.
00578  *
00579  * @since New in 1.2.
00580  */
00581 svn_error_t *svn_ra_get_commit_editor (svn_ra_session_t *session,
00582                                        const svn_delta_editor_t **editor,
00583                                        void **edit_baton,
00584                                        const char *log_msg,
00585                                        svn_commit_callback_t callback,
00586                                        void *callback_baton,
00587                                        apr_hash_t *lock_tokens,
00588                                        svn_boolean_t keep_locks,
00589                                        apr_pool_t *pool);
00590 
00591 /**
00592  * Fetch the contents and properties of file @a path at @a revision.
00593  * Interpret @a path relative to the URL in @a session.  Use
00594  * @a pool for all allocations.
00595  *
00596  * If @a revision is @c SVN_INVALID_REVNUM (meaning 'head') and
00597  * @a *fetched_rev is not @c NULL, then this function will set
00598  * @a *fetched_rev to the actual revision that was retrieved.  (Some
00599  * callers want to know, and some don't.) 
00600  *
00601  * If @a stream is non @c NULL, push the contents of the file at @a
00602  * stream, do not call svn_stream_close() when finished.
00603  *
00604  * If @a props is non @c NULL, set @a *props to contain the properties of 
00605  * the file.  This means @em all properties: not just ones controlled by
00606  * the user and stored in the repository fs, but non-tweakable ones
00607  * generated by the SCM system itself (e.g. 'wcprops', 'entryprops',
00608  * etc.)  The keys are <tt>const char *</tt>, values are 
00609  * <tt>@c svn_string_t *</tt>.
00610  *
00611  * The stream handlers for @a stream may not perform any RA
00612  * operations using @a session.
00613  *
00614  * @since New in 1.2.
00615  */
00616 svn_error_t *svn_ra_get_file (svn_ra_session_t *session,
00617                               const char *path,
00618                               svn_revnum_t revision,
00619                               svn_stream_t *stream,
00620                               svn_revnum_t *fetched_rev,
00621                               apr_hash_t **props,
00622                               apr_pool_t *pool);
00623 
00624 /**
00625  * If @a dirents is non @c NULL, set @a *dirents to contain all the entries
00626  * of directory @a path at @a revision.  The keys of @a dirents will be 
00627  * entry names (<tt>const char *</tt>), and the values dirents 
00628  * (<tt>@c svn_dirent_t *</tt>).  Use @a pool for all allocations.
00629  *
00630  * @a path is interpreted relative to the URL in @a session.
00631  *
00632  * If @a revision is @c SVN_INVALID_REVNUM (meaning 'head') and
00633  * @a *fetched_rev is not @c NULL, then this function will set
00634  * @a *fetched_rev to the actual revision that was retrieved.  (Some
00635  * callers want to know, and some don't.) 
00636  *
00637  * If @a props is non @c NULL, set @a *props to contain the properties of 
00638  * the directory.  This means @em all properties: not just ones controlled by
00639  * the user and stored in the repository fs, but non-tweakable ones
00640  * generated by the SCM system itself (e.g. 'wcprops', 'entryprops',
00641  * etc.)  The keys are <tt>const char *</tt>, values are 
00642  * <tt>@c svn_string_t *</tt>.
00643  *
00644  * @since New in 1.2.
00645  */
00646 svn_error_t *svn_ra_get_dir (svn_ra_session_t *session,
00647                              const char *path,
00648                              svn_revnum_t revision,
00649                              apr_hash_t **dirents,
00650                              svn_revnum_t *fetched_rev,
00651                              apr_hash_t **props,
00652                              apr_pool_t *pool);
00653 
00654 /**
00655  * Ask the RA layer to update a working copy.
00656  *
00657  * The client initially provides an @a update_editor/@a baton to the 
00658  * RA layer; this editor contains knowledge of where the change will
00659  * begin in the working copy (when @c open_root() is called).
00660  *
00661  * In return, the client receives a @a reporter/@a report_baton.  The
00662  * client then describes its working-copy revision numbers by making
00663  * calls into the @a reporter structure; the RA layer assumes that all
00664  * paths are relative to the URL used to open @a session.
00665  *
00666  * When finished, the client calls @a reporter->finish_report().  The
00667  * RA layer then does a complete drive of @a update_editor, ending with
00668  * close_edit(), to update the working copy.
00669  *
00670  * @a update_target is an optional single path component to restrict
00671  * the scope of the update to just that entry (in the directory
00672  * represented by the @a session's URL).  If @a update_target is the
00673  * empty string, the entire directory is updated.
00674  *
00675  * If @a recurse is true and the target is a directory, update
00676  * recursively; otherwise, update just the target and its immediate
00677  * entries, but not its child directories (if any).
00678  *
00679  * The working copy will be updated to @a revision_to_update_to, or the
00680  * "latest" revision if this arg is invalid.
00681  *
00682  * The caller may not perform any RA operations using @a session before
00683  * finishing the report, and may not perform any RA operations using
00684  * @a session from within the editing operations of @a update_editor.
00685  *
00686  * Use @a pool for memory allocation.
00687  *
00688  * @since New in 1.2.
00689  */
00690 svn_error_t *svn_ra_do_update (svn_ra_session_t *session,
00691                                const svn_ra_reporter2_t **reporter,
00692                                void **report_baton,
00693                                svn_revnum_t revision_to_update_to,
00694                                const char *update_target,
00695                                svn_boolean_t recurse,
00696                                const svn_delta_editor_t *update_editor,
00697                                void *update_baton,
00698                                apr_pool_t *pool);
00699 
00700 /**
00701  * Ask the RA layer to 'switch' a working copy to a new
00702  * @a switch_url;  it's another form of svn_ra_do_update().
00703  *
00704  * The client initially provides a @a switch_editor/@a baton to the RA
00705  * layer; this editor contains knowledge of where the change will
00706  * begin in the working copy (when open_root() is called). 
00707  *
00708  * In return, the client receives a @a reporter/@a report_baton.  The
00709  * client then describes its working-copy revision numbers by making
00710  * calls into the @a reporter structure; the RA layer assumes that all
00711  * paths are relative to the URL used to create @a session_baton.
00712  *
00713  * When finished, the client calls @a reporter->finish_report().  The
00714  * RA layer then does a complete drive of @a switch_editor, ending with
00715  * close_edit(), to switch the working copy.
00716  *
00717  * @a switch_target is an optional single path component will restrict
00718  * the scope of things affected by the switch to an entry in the
00719  * directory represented by the @a session's URL, or empty if the
00720  * entire directory is meant to be switched.
00721  *
00722  * If @a recurse is true and the target is a directory, switch
00723  * recursively; otherwise, switch just the target and its immediate
00724  * entries, but not its child directories (if any).
00725  *
00726  * The working copy will be switched to @a revision_to_switch_to, or the
00727  * "latest" revision if this arg is invalid.
00728  *
00729  * The caller may not perform any RA operations using
00730  * @a session before finishing the report, and may not perform
00731  * any RA operations using @a session_baton from within the editing
00732  * operations of @a switch_editor.
00733  *
00734  * Use @a pool for memory allocation.
00735  *
00736  * @since New in 1.2.
00737  */
00738 svn_error_t *svn_ra_do_switch (svn_ra_session_t *session,
00739                                const svn_ra_reporter2_t **reporter,
00740                                void **report_baton,
00741                                svn_revnum_t revision_to_switch_to,
00742                                const char *switch_target,
00743                                svn_boolean_t recurse,
00744                                const char *switch_url,
00745                                const svn_delta_editor_t *switch_editor,
00746                                void *switch_baton,
00747                                apr_pool_t *pool);
00748 
00749 /**
00750  * Ask the RA layer to describe the status of a working copy with respect
00751  * to @a revision of the repository (or HEAD, if @a revision is invalid).
00752  *
00753  * The client initially provides a @a status_editor/@a baton to the RA
00754  * layer; this editor contains knowledge of where the change will
00755  * begin in the working copy (when open_root() is called).
00756  *
00757  * In return, the client receives a @a reporter/@a report_baton. The
00758  * client then describes its working-copy revision numbers by making
00759  * calls into the @a reporter structure; the RA layer assumes that all
00760  * paths are relative to the URL used to open @a session.
00761  *
00762  * When finished, the client calls @a reporter->finish_report(). The RA
00763  * layer then does a complete drive of @a status_editor, ending with
00764  * close_edit(), to report, essentially, what would be modified in
00765  * the working copy were the client to call do_update().
00766  * @a status_target is an optional single path component will restrict
00767  * the scope of the status report to an entry in the directory
00768  * represented by the @a session_baton's URL, or empty if the entire
00769  * directory is meant to be examined.
00770  *
00771  * If @a recurse is true and the target is a directory, get status
00772  * recursively; otherwise, get status for just the target and its
00773  * immediate entries, but not its child directories (if any).
00774  *
00775  * The caller may not perform any RA operations using @a session
00776  * before finishing the report, and may not perform any RA operations
00777  * using @a session from within the editing operations of @a status_editor.
00778  *
00779  * Use @a pool for memory allocation.
00780  *
00781  * @since New in 1.2.
00782  */
00783 svn_error_t *svn_ra_do_status (svn_ra_session_t *session,
00784                                const svn_ra_reporter2_t **reporter,
00785                                void **report_baton,
00786                                const char *status_target,
00787                                svn_revnum_t revision,
00788                                svn_boolean_t recurse,
00789                                const svn_delta_editor_t *status_editor,
00790                                void *status_baton,
00791                                apr_pool_t *pool);
00792 
00793 /**
00794  * Ask the RA layer to 'diff' a working copy against @a versus_url;
00795  * it's another form of svn_ra_do_update().
00796  *
00797  * @note This function cannot be used to diff a single file, only a
00798  * working copy directory.  See the svn_ra_do_switch() function 
00799  * for more details.
00800  *
00801  * The client initially provides a @a diff_editor/@a baton to the RA
00802  * layer; this editor contains knowledge of where the common diff
00803  * root is in the working copy (when open_root() is called). 
00804  *
00805  * In return, the client receives a @a reporter/@a report_baton. The
00806  * client then describes its working-copy revision numbers by making
00807  * calls into the @a reporter structure; the RA layer assumes that all
00808  * paths are relative to the URL used to open @a session.
00809  *
00810  * When finished, the client calls @a reporter->finish_report().  The
00811  * RA layer then does a complete drive of @a diff_editor, ending with
00812  * close_edit(), to transmit the diff.
00813  *
00814  * @a diff_target is an optional single path component will restrict
00815  * the scope of the diff to an entry in the directory represented by
00816  * the @a session's URL, or empty if the entire directory is meant to be
00817  * one of the diff paths.
00818  *
00819  * The working copy will be diffed against @a versus_url as it exists
00820  * in revision @a revision, or as it is in head if @a revision is
00821  * @c SVN_INVALID_REVNUM.
00822  *
00823  * Use @a ignore_ancestry to control whether or not items being
00824  * diffed will be checked for relatedness first.  Unrelated items
00825  * are typically transmitted to the editor as a deletion of one thing
00826  * and the addition of another, but if this flag is @c TRUE,
00827  * unrelated items will be diffed as if they were related.
00828  *
00829  * If @a recurse is true and the target is a directory, diff
00830  * recursively; otherwise, diff just target and its immediate entries,
00831  * but not its child directories (if any).
00832  *
00833  * The caller may not perform any RA operations using @a session before
00834  * finishing the report, and may not perform any RA operations using
00835  * @a session from within the editing operations of @a diff_editor.
00836  *
00837  * Use @a pool for memory allocation.
00838  *
00839  * @since New in 1.2.
00840  */
00841 svn_error_t *svn_ra_do_diff (svn_ra_session_t *session,
00842                              const svn_ra_reporter2_t **reporter,
00843                              void **report_baton,
00844                              svn_revnum_t revision,
00845                              const char *diff_target,
00846                              svn_boolean_t recurse,
00847                              svn_boolean_t ignore_ancestry,
00848                              const char *versus_url,
00849                              const svn_delta_editor_t *diff_editor,
00850                              void *diff_baton,
00851                              apr_pool_t *pool);
00852 
00853 /**
00854  * Invoke @a receiver with @a receiver_baton on each log message from
00855  * @a start to @a end.  @a start may be greater or less than @a end; 
00856  * this just controls whether the log messages are processed in descending 
00857  * or ascending revision number order.
00858  *
00859  * If @a start or @a end is @c SVN_INVALID_REVNUM, it defaults to youngest.
00860  *
00861  * If @a paths is non-null and has one or more elements, then only show
00862  * revisions in which at least one of @a paths was changed (i.e., if
00863  * file, text or props changed; if dir, props changed or an entry
00864  * was added or deleted).  Each path is an <tt>const char *</tt>, relative 
00865  * to the @a session's common parent.
00866  *
00867  * If @a limit is non-zero only invoke @a receiver on the first @a limit
00868  * logs.
00869  *
00870  * If @a discover_changed_paths, then each call to receiver passes a
00871  * <tt>const apr_hash_t *</tt> for the receiver's @a changed_paths argument;
00872  * the hash's keys are all the paths committed in that revision.
00873  * Otherwise, each call to receiver passes null for @a changed_paths.
00874  *
00875  * If @a strict_node_history is set, copy history will not be traversed
00876  * (if any exists) when harvesting the revision logs for each path.
00877  *
00878  * If any invocation of @a receiver returns error, return that error
00879  * immediately and without wrapping it.
00880  *
00881  * If @a start or @a end is a non-existent revision, return the error
00882  * @c SVN_ERR_FS_NO_SUCH_REVISION, without ever invoking @a receiver.
00883  *
00884  * See also the documentation for @c svn_log_message_receiver_t.
00885  *
00886  * The caller may not invoke any RA operations using @a session from
00887  * within @a receiver.
00888  *
00889  * Use @a pool for memory allocation.
00890  *
00891  * @since New in 1.2.
00892  */
00893 svn_error_t *svn_ra_get_log (svn_ra_session_t *session,
00894                              const apr_array_header_t *paths,
00895                              svn_revnum_t start,
00896                              svn_revnum_t end,
00897                              int limit,
00898                              svn_boolean_t discover_changed_paths,
00899                              svn_boolean_t strict_node_history,
00900                              svn_log_message_receiver_t receiver,
00901                              void *receiver_baton,
00902                              apr_pool_t *pool);
00903 
00904 /**
00905  * Set @a *kind to the node kind associated with @a path at @a revision.  
00906  * If @a path does not exist under @a revision, set @a *kind to 
00907  * @c svn_node_none.  @a path is relative to the @a session's parent URL.
00908  *
00909  * Use @a pool for memory allocation.
00910  *
00911  * @since New in 1.2.
00912  */
00913 svn_error_t *svn_ra_check_path (svn_ra_session_t *session,
00914                                 const char *path,
00915                                 svn_revnum_t revision,
00916                                 svn_node_kind_t *kind,
00917                                 apr_pool_t *pool);
00918 
00919 /**
00920  * Set @a *dirent to an @c svn_dirent_t associated with @a path at @a
00921  * revision.  @a path is relative to the @a session's parent's URL.
00922  * If @a path does not exist in @a revision, set @a *dirent to NULL.
00923  *
00924  * Use @a pool for memory allocation.
00925  *
00926  * @since New in 1.2.
00927  */
00928 svn_error_t *svn_ra_stat (svn_ra_session_t *session,
00929                           const char *path,
00930                           svn_revnum_t revision,
00931                           svn_dirent_t **dirent,
00932                           apr_pool_t *pool);
00933 
00934 
00935 /**
00936  * Set @a *uuid to the repository's UUID.
00937  *
00938  * @note The UUID has the same lifetime as the @a session.
00939  *
00940  * Use @a pool for temporary memory allocation.
00941  *
00942  * @since New in 1.2.
00943  */
00944 svn_error_t *svn_ra_get_uuid (svn_ra_session_t *session,
00945                               const char **uuid,
00946                               apr_pool_t *pool);
00947 
00948 /**
00949  * Set @a *url to the repository's root URL.  The value will not include
00950  * a trailing '/'.  The returned URL is guaranteed to be a prefix of the
00951  * @a session's URL.
00952  *
00953  * @note The URL has the same lifetime as the @a session.
00954  *
00955  * Use @a pool for temporary memory allocation.
00956  *
00957  * @since New in 1.2.
00958  */
00959 svn_error_t *svn_ra_get_repos_root (svn_ra_session_t *session,
00960                                     const char **url,
00961                                     apr_pool_t *pool);
00962 
00963 /**
00964  * Set @a *locations to the locations (at the repository revisions
00965  * @a location_revisions) of the file identified by @a path in
00966  * @a peg_revision.  @a path is relative to the URL to which
00967  * @a session was opened.  @a location_revisions is an array of
00968  * @c svn_revnum_t's.  @a *locations will be a mapping from the revisions to
00969  * their appropriate absolute paths.  If the file doesn't exist in a
00970  * location_revision, that revision will be ignored.
00971  *
00972  * Use @a pool for all allocations.
00973  *
00974  * @note This functionality is not available in pre-1.1 servers.  If the
00975  * server doesn't implement it, an @c SVN_ERR_RA_NOT_IMPLEMENTED error is
00976  * returned.
00977  *
00978  * @since New in 1.2.
00979  */
00980 svn_error_t *svn_ra_get_locations (svn_ra_session_t *session,
00981                                    apr_hash_t **locations,
00982                                    const char *path,
00983                                    svn_revnum_t peg_revision,
00984                                    apr_array_header_t *location_revisions,
00985                                    apr_pool_t *pool);
00986 
00987 /**
00988  * Retrieve a subset of the interesting revisions of a file @a path
00989  * as seen in revision @a end (see svn_fs_history_prev() for a
00990  * definition of "interesting revisions").  Invoke @a handler with
00991  * @a handler_baton as its first argument for each such revision.
00992  * @a session is an open RA session.  Use @a pool for all allocations.
00993  *
00994  * If there is an interesting revision of the file that is less than or
00995  * equal to @a start, the iteration will begin at that revision.
00996  * Else, the iteration will begin at the first revision of the file in
00997  * the repository, which has to be less than or equal to @a end.  Note
00998  * that if the function succeeds, @a handler will have been called at
00999  * least once.
01000  *
01001  * In a series of calls to @a handler, the file contents for the first
01002  * interesting revision will be provided as a text delta against the
01003  * empty file.  In the following calls, the delta will be against the
01004  * fulltext contents for the previous call.
01005  *
01006  * @note This functionality is not available in pre-1.1 servers.  If the
01007  * server doesn't implement it, an @c SVN_ERR_RA_NOT_IMPLEMENTED error is
01008  * returned.
01009  *
01010  * @since New in 1.2.
01011  */
01012 svn_error_t *svn_ra_get_file_revs (svn_ra_session_t *session,
01013                                    const char *path,
01014                                    svn_revnum_t start,
01015                                    svn_revnum_t end,
01016                                    svn_ra_file_rev_handler_t handler,
01017                                    void *handler_baton,
01018                                    apr_pool_t *pool);
01019 
01020 /**
01021  * Lock each path in @a path_revs, which is a hash whose keys are the
01022  * paths to be locked, and whose values are the corresponding bas
01023  * revisions for each path.
01024  *
01025  * Note that locking is never anonymous, so any server implementing
01026  * this function will have to "pull" a username from the client, if
01027  * it hasn't done so already.
01028  *
01029  * @a comment is optional: it's either an xml-escapable string
01030  * which describes the lock, or it is NULL.
01031  *
01032  * If any path is already locked by a different user, then call @a
01033  * lock_func/@a lock_baton with an error.  If @a steal_lock is true,
01034  * then "steal" the existing lock(s) anyway, even if the RA username
01035  * does not match the current lock's owner.  Delete any lock on the
01036  * path, and unconditionally create a new lock.
01037  *
01038  * For each path, if its base revision (in @a path_revs) is a valid
01039  * revnum, then do an out-of-dateness check.  If the revnum is less
01040  * than the last-changed-revision of any path (or if a path doesn't
01041  * exist in HEAD), call @a lock_func/@a lock_baton with an
01042  * SVN_ERR_RA_OUT_OF_DATE error.
01043  *
01044  * After successfully locking a file, @a lock_func is called with the
01045  * @a lock_baton.
01046  *
01047  * Use @a pool for temporary allocations.
01048  *
01049  * @since New in 1.2.
01050  */
01051 svn_error_t *svn_ra_lock (svn_ra_session_t *session,
01052                           apr_hash_t *path_revs,
01053                           const char *comment,
01054                           svn_boolean_t steal_lock,
01055                           svn_ra_lock_callback_t lock_func, 
01056                           void *lock_baton,
01057                           apr_pool_t *pool);
01058 
01059 /**
01060  * Remove the repository lock for each path in @a path_tokens.
01061  * @a path_tokens is a hash whose keys are the paths to be locked, and
01062  * whose values are the corresponding lock tokens for each path.  If
01063  * the path has no corresponding lock token, or if @a break_lock is TRUE,
01064  * then the corresponding value shall be "".
01065  * 
01066  * Note that unlocking is never anonymous, so any server
01067  * implementing this function will have to "pull" a username from
01068  * the client, if it hasn't done so already.
01069  *
01070  * If @a token points to a lock, but the RA username doesn't match the
01071  * lock's owner, call @a lockfunc/@a lock_baton with an error.  If @a
01072  * break_lock is true, however, instead allow the lock to be "broken"
01073  * by the RA user.
01074  *
01075  * After successfully unlocking a path, @a lock_func is called with
01076  * the @a lock_baton.
01077  *
01078  * Use @a pool for temporary allocations.
01079  *
01080  * @since New in 1.2.
01081  */
01082 svn_error_t *svn_ra_unlock (svn_ra_session_t *session,
01083                             apr_hash_t *path_tokens,
01084                             svn_boolean_t break_lock,
01085                             svn_ra_lock_callback_t lock_func, 
01086                             void *lock_baton,
01087                             apr_pool_t *pool);
01088 
01089 /**  
01090  * If @a path is locked, set @a *lock to an svn_lock_t which
01091  * represents the lock, allocated in @a pool.  If @a path is not
01092  * locked, set @a *lock to NULL.
01093  *
01094  * @since New in 1.2.
01095  */
01096 svn_error_t *svn_ra_get_lock (svn_ra_session_t *session,
01097                               svn_lock_t **lock,
01098                               const char *path,
01099                               apr_pool_t *pool);
01100 
01101 /**
01102  * Set @a *locks to a hashtable which represents all locks on or
01103  * below @a path.
01104  *
01105  * The hashtable maps (const char *) absolute fs paths to (const
01106  * svn_lock_t *) structures.  The hashtable -- and all keys and
01107  * values -- are allocated in @a pool.
01108  *
01109  * @note It is not considered an error for @a path to not exist in HEAD.
01110  * Such a search will simply return no locks.
01111  *
01112  * @note This functionality is not available in pre-1.2 servers.  If the
01113  * server doesn't implement it, an @c SVN_ERR_RA_NOT_IMPLEMENTED error is
01114  * returned.
01115  *
01116  * @since New in 1.2.
01117  */
01118 svn_error_t *svn_ra_get_locks (svn_ra_session_t *session,
01119                                apr_hash_t **locks,
01120                                const char *path,
01121                                apr_pool_t *pool);
01122 
01123 /**
01124  * Append a textual list of all available RA modules to the stringbuf
01125  * @a output.
01126  *
01127  * @since New in 1.2.
01128  */
01129 svn_error_t *svn_ra_print_modules (svn_stringbuf_t *output,
01130                                    apr_pool_t *pool);
01131 
01132 
01133 /**
01134  * Similar to svn_ra_print_modules().
01135  * @a ra_baton is ignored.
01136  *
01137  * @deprecated Provided for backward compatibility with the 1.1 API.
01138  */
01139 svn_error_t *svn_ra_print_ra_libraries (svn_stringbuf_t **descriptions,
01140                                         void *ra_baton,
01141                                         apr_pool_t *pool);
01142 
01143 
01144 
01145 /**
01146  * Using this callback struct is similar to calling the newer public
01147  * interface that is based on @c svn_ra_session_t.
01148  *
01149  * @deprecated Provided for backward compatibility with the 1.1 API.
01150  */
01151 typedef struct svn_ra_plugin_t
01152 {
01153   /** The proper name of the RA library, (like "ra_dav" or "ra_local") */
01154   const char *name;         
01155   
01156   /** Short doc string printed out by `svn --version` */
01157   const char *description;
01158 
01159   /* The vtable hooks */
01160 
01161   /** Call svn_ra_open() and set @a session_baton to an object representing
01162    * the new session.  All other arguments are passed to svn_ra_open().
01163    */
01164   svn_error_t *(*open) (void **session_baton,
01165                         const char *repos_URL,
01166                         const svn_ra_callbacks_t *callbacks,
01167                         void *callback_baton,
01168                         apr_hash_t *config,
01169                         apr_pool_t *pool);
01170 
01171   /** Call svn_ra_get_latest_revnum() with the session associated with
01172    * @a session_baton and all other arguments.
01173    */
01174   svn_error_t *(*get_latest_revnum) (void *session_baton,
01175                                      svn_revnum_t *latest_revnum,
01176                                      apr_pool_t *pool);
01177 
01178   /** Call svn_ra_get_dated_revision() with the session associated with
01179    * @a session_baton and all other arguments.
01180    */
01181   svn_error_t *(*get_dated_revision) (void *session_baton,
01182                                       svn_revnum_t *revision,
01183                                       apr_time_t tm,
01184                                       apr_pool_t *pool);
01185 
01186   /** Call svn_ra_change_rev_prop() with the session associated with
01187    * @a session_baton and all other arguments.
01188    */
01189   svn_error_t *(*change_rev_prop) (void *session_baton,
01190                                    svn_revnum_t rev,
01191                                    const char *name,
01192                                    const svn_string_t *value,
01193                                    apr_pool_t *pool);
01194 
01195   /** Call svn_ra_rev_proplist() with the session associated with
01196    * @a session_baton and all other arguments.
01197    */
01198   svn_error_t *(*rev_proplist) (void *session_baton,
01199                                 svn_revnum_t rev,
01200                                 apr_hash_t **props,
01201                                 apr_pool_t *pool);
01202 
01203   /** Call svn_ra_rev_prop() with the session associated with
01204    * @a session_baton and all other arguments.
01205    */
01206   svn_error_t *(*rev_prop) (void *session_baton,
01207                             svn_revnum_t rev,
01208                             const char *name,
01209                             svn_string_t **value,
01210                             apr_pool_t *pool);
01211                                    
01212   /** Call svn_ra_get_commit_editor() with the session associated with
01213    * @a session_baton and all other arguments plus @a lock_tokens set to
01214    * @c NULL and @a keep_locks set to @c TRUE.
01215    */
01216   svn_error_t *(*get_commit_editor) (void *session_baton,
01217                                      const svn_delta_editor_t **editor,
01218                                      void **edit_baton,
01219                                      const char *log_msg,
01220                                      svn_commit_callback_t callback,
01221                                      void *callback_baton,
01222                                      apr_pool_t *pool);
01223 
01224   /** Call svn_ra_get_file() with the session associated with
01225    * @a session_baton and all other arguments.
01226    */
01227   svn_error_t *(*get_file) (void *session_baton,
01228                             const char *path,
01229                             svn_revnum_t revision,
01230                             svn_stream_t *stream,
01231                             svn_revnum_t *fetched_rev,
01232                             apr_hash_t **props,
01233                             apr_pool_t *pool);
01234 
01235   /** Call svn_ra_get_dir() with the session associated with
01236    * @a session_baton and all other arguments.
01237    */
01238   svn_error_t *(*get_dir) (void *session_baton,
01239                            const char *path,
01240                            svn_revnum_t revision,
01241                            apr_hash_t **dirents,
01242                            svn_revnum_t *fetched_rev,
01243                            apr_hash_t **props,
01244                            apr_pool_t *pool);
01245 
01246   /** Call svn_ra_do_update() with the session associated with
01247    * @a session_baton and all other arguments.
01248    */
01249   svn_error_t *(*do_update) (void *session_baton,
01250                              const svn_ra_reporter_t **reporter,
01251                              void **report_baton,
01252                              svn_revnum_t revision_to_update_to,
01253                              const char *update_target,
01254                              svn_boolean_t recurse,
01255                              const svn_delta_editor_t *update_editor,
01256                              void *update_baton,
01257                              apr_pool_t *pool);
01258 
01259   /** Call svn_ra_do_switch() with the session associated with
01260    * @a session_baton and all other arguments.
01261    */
01262   svn_error_t *(*do_switch) (void *session_baton,
01263                              const svn_ra_reporter_t **reporter,
01264                              void **report_baton,
01265                              svn_revnum_t revision_to_switch_to,
01266                              const char *switch_target,
01267                              svn_boolean_t recurse,
01268                              const char *switch_url,
01269                              const svn_delta_editor_t *switch_editor,
01270                              void *switch_baton,
01271                              apr_pool_t *pool);
01272 
01273   /** Call svn_ra_do_status() with the session associated with
01274    * @a session_baton and all other arguments.
01275    */
01276   svn_error_t *(*do_status) (void *session_baton,
01277                              const svn_ra_reporter_t **reporter,
01278                              void **report_baton,
01279                              const char *status_target,
01280                              svn_revnum_t revision,
01281                              svn_boolean_t recurse,
01282                              const svn_delta_editor_t *status_editor,
01283                              void *status_baton,
01284                              apr_pool_t *pool);
01285 
01286   /** Call svn_ra_do_diff() with the session associated with
01287    * @a session_baton and all other arguments.
01288    */
01289   svn_error_t *(*do_diff) (void *session_baton,
01290                            const svn_ra_reporter_t **reporter,
01291                            void **report_baton,
01292                            svn_revnum_t revision,
01293                            const char *diff_target,
01294                            svn_boolean_t recurse,
01295                            svn_boolean_t ignore_ancestry,
01296                            const char *versus_url,
01297                            const svn_delta_editor_t *diff_editor,
01298                            void *diff_baton,
01299                            apr_pool_t *pool);
01300 
01301   /** Call svn_ra_get_log() with the session associated with
01302    * @a session_baton and all other arguments.  @a limit is set to 0.
01303    */
01304   svn_error_t *(*get_log) (void *session_baton,
01305                            const apr_array_header_t *paths,
01306                            svn_revnum_t start,
01307                            svn_revnum_t end,
01308                            svn_boolean_t discover_changed_paths,
01309                            svn_boolean_t strict_node_history,
01310                            svn_log_message_receiver_t receiver,
01311                            void *receiver_baton,
01312                            apr_pool_t *pool);
01313 
01314   /** Call svn_ra_check_path() with the session associated with
01315    * @a session_baton and all other arguments.
01316    */
01317   svn_error_t *(*check_path) (void *session_baton,
01318                               const char *path,
01319                               svn_revnum_t revision,
01320                               svn_node_kind_t *kind,
01321                               apr_pool_t *pool);
01322 
01323   /** Call svn_ra_get_uuid() with the session associated with
01324    * @a session_baton and all other arguments.
01325    */
01326   svn_error_t *(*get_uuid) (void *session_baton,
01327                             const char **uuid,
01328                             apr_pool_t *pool);
01329 
01330   /** Call svn_ra_get_repos_root() with the session associated with
01331    * @a session_baton and all other arguments.
01332    */
01333   svn_error_t *(*get_repos_root) (void *session_baton,
01334                                   const char **url,
01335                                   apr_pool_t *pool);
01336 
01337   /**
01338    * Call svn_ra_get_locations() with the session associated with
01339    * @a session_baton and all other arguments.
01340    *
01341    * @since New in 1.1.
01342    */
01343   svn_error_t *(*get_locations) (void *session_baton,
01344                                  apr_hash_t **locations,
01345                                  const char *path,
01346                                  svn_revnum_t peg_revision,
01347                                  apr_array_header_t *location_revisions,
01348                                  apr_pool_t *pool);
01349 
01350   /**
01351    * Call svn_ra_get_file_revs() with the session associated with
01352    * @a session_baton and all other arguments.
01353    *
01354    * @since New in 1.1.
01355    */
01356   svn_error_t *(*get_file_revs) (void *session_baton,
01357                                  const char *path,
01358                                  svn_revnum_t start,
01359                                  svn_revnum_t end,
01360                                  svn_ra_file_rev_handler_t handler,
01361                                  void *handler_baton,
01362                                  apr_pool_t *pool);
01363 
01364   /**
01365    * Return the plugin's version information.
01366    *
01367    * @since New in 1.1.
01368    */
01369   const svn_version_t *(*get_version) (void);
01370 
01371   
01372 } svn_ra_plugin_t;
01373 
01374 /**
01375  * All "ra_FOO" implementations *must* export a function named
01376  * svn_ra_FOO_init() of type @c svn_ra_init_func_t.
01377  *
01378  * When called by libsvn_client, this routine adds an entry (or
01379  * entries) to the hash table for any URL schemes it handles.  The hash
01380  * value must be of type (<tt>@c svn_ra_plugin_t *</tt>).  @a pool is a 
01381  * pool for allocating configuration / one-time data.
01382  *
01383  * This type is defined to use the "C Calling Conventions" to ensure that
01384  * abi_version is the first parameter. The RA plugin must check that value
01385  * before accessing the other parameters.
01386  *
01387  * ### need to force this to be __cdecl on Windows... how??
01388  *
01389  * @deprecated Provided for backward compatibility with the 1.1 API.
01390  */
01391 typedef svn_error_t *(*svn_ra_init_func_t) (int abi_version,
01392                                             apr_pool_t *pool,
01393                                             apr_hash_t *hash);
01394 
01395 /**
01396  * The current ABI (Application Binary Interface) version for the
01397  * RA plugin model. This version number will change when the ABI
01398  * between the SVN core (e.g. libsvn_client) and the RA plugin changes.
01399  *
01400  * An RA plugin should verify that the passed version number is acceptable
01401  * before accessing the rest of the parameters, and before returning any
01402  * information.
01403  *
01404  * It is entirely acceptable for an RA plugin to accept multiple ABI
01405  * versions. It can simply interpret the parameters based on the version,
01406  * and it can return different plugin structures.
01407  *
01408  *
01409  * <pre>
01410  * VSN  DATE        REASON FOR CHANGE
01411  * ---  ----------  ------------------------------------------------
01412  *   1  2001-02-17  Initial revision.
01413  *   2  2004-06-29  Preparing for svn 1.1, which adds new RA vtable funcs.
01414  *      2005-01-19  Rework the plugin interface and don't provide the vtable
01415  *                  to the client.  Separate ABI versions are no longer used.
01416  * </pre>
01417  * 
01418  * @deprecated Provided for backward compatibility with the 1.0 API.
01419  */
01420 #define SVN_RA_ABI_VERSION      2
01421 
01422 /* Public RA implementations. */
01423 
01424 /** Initialize libsvn_ra_dav.
01425  *
01426  * @deprecated Provided for backward compatibility with the 1.1 API. */
01427 svn_error_t * svn_ra_dav_init (int abi_version,
01428                                apr_pool_t *pool,
01429                                apr_hash_t *hash);
01430 
01431 /** Initialize libsvn_ra_local.
01432  *
01433  * @deprecated Provided for backward compatibility with the 1.1 API. */
01434 svn_error_t * svn_ra_local_init (int abi_version,
01435                                  apr_pool_t *pool,
01436                                  apr_hash_t *hash);
01437 
01438 /** Initialize libsvn_ra_svn.
01439  *
01440  * @deprecated Provided for backward compatibility with the 1.1 API. */
01441 svn_error_t * svn_ra_svn_init (int abi_version,
01442                                apr_pool_t *pool,
01443                                apr_hash_t *hash);
01444 
01445 
01446 
01447 /**
01448  * Initialize the compatibility wrapper, using @a pool for any allocations.
01449  * The caller must hold on to @a ra_baton as long as the RA library is used.
01450  *
01451  * @deprecated Provided for backward compatibility with the 1.1 API.
01452  */
01453 svn_error_t *svn_ra_init_ra_libs (void **ra_baton, apr_pool_t *pool);
01454 
01455 /**
01456  * Return an RA vtable-@a library which can handle URL.  A number of
01457  * svn_client_* routines will call this internally, but client apps might
01458  * use it too.  $a ra_baton is a baton obtained by a call to
01459  * svn_ra_init_ra_libs().
01460  *
01461  * @deprecated Provided for backward compatibility with the 1.1 API.
01462  */
01463 svn_error_t *svn_ra_get_ra_library (svn_ra_plugin_t **library,
01464                                     void *ra_baton,
01465                                     const char *url,
01466                                     apr_pool_t *pool);
01467 
01468 #ifdef __cplusplus
01469 }
01470 #endif /* __cplusplus */
01471 
01472 #endif  /* SVN_RA_H */
01473                            

Generated on Mon Jun 5 17:10:17 2006 for Subversion by  doxygen 1.3.9.1