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

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 structures related to 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 /** This is a function type which allows the RA layer to fetch working
00044  * copy (WC) properties.
00045  *
00046  * The @a baton is provided along with the function pointer and should
00047  * be passed back in. This will be the @a callback_baton or the 
00048  * @a close_baton as appropriate.
00049  *
00050  * @a path is relative to the "root" of the session, defined by the 
00051  * @a repos_url passed to the @c RA->open() vtable call.
00052  *
00053  * @a name is the name of the property to fetch. If the property is present,
00054  * then it is returned in @a value. Otherwise, @a *value is set to @c NULL.
00055  */
00056 typedef svn_error_t *(*svn_ra_get_wc_prop_func_t) (void *baton,
00057                                                    const char *relpath,
00058                                                    const char *name,
00059                                                    const svn_string_t **value,
00060                                                    apr_pool_t *pool);
00061 
00062 /** This is a function type which allows the RA layer to store new
00063  * working copy properties during update-like operations.  See the
00064  * comments for @c svn_ra_get_wc_prop_func_t for @a baton, @a path, and 
00065  * @a name. The @a value is the value that will be stored for the property; 
00066  * a null @a value means the property will be deleted.
00067  */
00068 typedef svn_error_t *(*svn_ra_set_wc_prop_func_t) (void *baton,
00069                                                    const char *path,
00070                                                    const char *name,
00071                                                    const svn_string_t *value,
00072                                                    apr_pool_t *pool);
00073 
00074 /** This is a function type which allows the RA layer to store new
00075  * working copy properties as part of a commit.  See the comments for
00076  * @c svn_ra_get_wc_prop_func_t for @a baton, @a path, and @a name.  
00077  * The @a value is the value that will be stored for the property; a 
00078  * @c NULL @a value means the property will be deleted.
00079  *
00080  * Note that this might not actually store the new property before
00081  * returning, but instead schedule it to be changed as part of
00082  * post-commit processing (in which case a successful commit means the
00083  * properties got written).  Thus, during the commit, it is possible
00084  * to invoke this function to set a new value for a wc prop, then read
00085  * the wc prop back from the working copy and get the *old* value.
00086  * Callers beware.
00087  */
00088 typedef svn_error_t *(*svn_ra_push_wc_prop_func_t) (void *baton,
00089                                                     const char *path,
00090                                                     const char *name,
00091                                                     const svn_string_t *value,
00092                                                     apr_pool_t *pool);
00093 
00094 /** This is a function type which allows the RA layer to invalidate
00095  * (i.e., remove) wcprops.  See the documentation for
00096  * @c svn_ra_get_wc_prop_func_t for @a baton, @a path, and @a name.
00097  *
00098  * Unlike @c svn_ra_push_wc_prop_func_t, this has immediate effect.  If
00099  * it returns success, the wcprops have been removed.
00100  */
00101 typedef svn_error_t *(*svn_ra_invalidate_wc_props_func_t) (void *baton,
00102                                                            const char *path,
00103                                                            const char *name,
00104                                                            apr_pool_t *pool);
00105 
00106 
00107 /** A function type for retrieving the youngest revision from a repos. */
00108 typedef svn_error_t *(*svn_ra_get_latest_revnum_func_t) 
00109        (void *session_baton,
00110         svn_revnum_t *latest_revnum);
00111 
00112 
00113 /** The update Reporter.
00114  *
00115  * A vtable structure which allows a working copy to describe a subset
00116  * (or possibly all) of its working-copy to an RA layer, for the
00117  * purposes of an update, switch, status, or diff operation.
00118  *
00119  * Paths for report calls are relative to the target (not the anchor)
00120  * of the operation.  Report calls must be made in depth-first order:
00121  * parents before children, all children of a parent before any
00122  * siblings of the parent.  The first report call must be a set_path
00123  * with a @a path argument of "" and a valid revision.  (If the target
00124  * of the operation is locally deleted or missing, use the anchor's
00125  * revision.)  If the target of the operation is deleted or switched
00126  * relative to the anchor, follow up the initial set_path call with a
00127  * link_path or delete_path call with a @a path argument of "" to
00128  * indicate that.  In no other case may there be two report
00129  * descriptions for the same path.  If the target of the operation is
00130  * a locally added file or directory (which previously did not exist),
00131  * it may be reported as having revision 0 or as having the parent
00132  * directory's revision.
00133  */
00134 typedef struct svn_ra_reporter_t
00135 {
00136   /** Describe a working copy @a path as being at a particular @a revision.  
00137    *
00138    * If @a START_EMPTY is set and @a path is a directory, the
00139    * implementor should assume the directory has no entries or props.
00140    *
00141    * This will *override* any previous @c set_path() calls made on parent
00142    * paths.  @a path is relative to the URL specified in @c open().
00143    *
00144    * All temporary allocations are done in @a pool.
00145    */
00146   svn_error_t *(*set_path) (void *report_baton,
00147                             const char *path,
00148                             svn_revnum_t revision,
00149                             svn_boolean_t start_empty,
00150                             apr_pool_t *pool);
00151 
00152   /** Describing a working copy @a path as missing.
00153    *
00154    * All temporary allocations are done in @a pool.
00155    */
00156   svn_error_t *(*delete_path) (void *report_baton,
00157                                const char *path,
00158                                apr_pool_t *pool);
00159     
00160   /** Like @c set_path(), but differs in that @a path in the working copy
00161    * (relative to the root of the report driver) isn't a reflection of
00162    * @a path in the repository (relative to the URL specified when
00163    * opening the RA layer), but is instead a reflection of a different
00164    * repository @a url at @a revision.
00165    *
00166    * If @a START_EMPTY is set and @a path is a directory,
00167    * the implementor should assume the directory has no entries or props.
00168    *
00169    * All temporary allocations are done in @a pool.
00170    */
00171   svn_error_t *(*link_path) (void *report_baton,
00172                              const char *path,
00173                              const char *url,
00174                              svn_revnum_t revision,
00175                              svn_boolean_t start_empty,
00176                              apr_pool_t *pool);
00177 
00178   /** WC calls this when the state report is finished; any directories
00179    * or files not explicitly `set' above are assumed to be at the
00180    * baseline revision originally passed into @c do_update().
00181    */
00182   svn_error_t *(*finish_report) (void *report_baton,
00183                                  apr_pool_t *pool);
00184 
00185   /** If an error occurs during a report, this routine should cause the
00186    * filesystem transaction to be aborted & cleaned up.
00187    */
00188   svn_error_t *(*abort_report) (void *report_baton,
00189                                 apr_pool_t *pool);
00190 
00191 } svn_ra_reporter_t;
00192 
00193 
00194 
00195 /** A collection of callbacks implemented by libsvn_client which allows
00196  * an RA layer to "pull" information from the client application, or 
00197  * possibly store information.
00198  *
00199  * A collection of callbacks implemented by libsvn_client which allows
00200  * an RA layer to "pull" information from the client application, or
00201  * possibly store information.  libsvn_client passes this vtable to
00202  * @c RA->open().  
00203  *
00204  * Each routine takes a @a callback_baton originally provided with the
00205  * vtable.
00206  */
00207 typedef struct svn_ra_callbacks_t
00208 {
00209   /** Open a unique temporary file for writing in the working copy.
00210    * This file will be automatically deleted when @a fp is closed.
00211    */
00212   svn_error_t *(*open_tmp_file) (apr_file_t **fp,
00213                                  void *callback_baton,
00214                                  apr_pool_t *pool);
00215   
00216   /** An authentication baton, created by the application, which is
00217    * capable of retrieving all known types of credentials.
00218    */
00219   svn_auth_baton_t *auth_baton;
00220 
00221   /*** The following items may be set to NULL to disallow the RA layer
00222        to perform the respective operations of the vtable functions.
00223        Perhaps WC props are not defined or are in invalid for this
00224        session, or perhaps the commit operation this RA session will
00225        perform is a server-side only one that shouldn't do post-commit
00226        processing on a working copy path.  ***/
00227 
00228   /** Fetch working copy properties.
00229    *
00230    *<pre> ### we might have a problem if the RA layer ever wants a property
00231    * ### that corresponds to a different revision of the file than
00232    * ### what is in the WC. we'll cross that bridge one day...</pre>
00233    */
00234   svn_ra_get_wc_prop_func_t get_wc_prop;
00235 
00236   /** Immediately set new values for working copy properties. */
00237   svn_ra_set_wc_prop_func_t set_wc_prop;
00238 
00239   /** Schedule new values for working copy properties. */
00240   svn_ra_push_wc_prop_func_t push_wc_prop;
00241 
00242   /** Invalidate working copy properties. */
00243   svn_ra_invalidate_wc_props_func_t invalidate_wc_props;
00244 
00245 } svn_ra_callbacks_t;
00246 
00247 
00248 
00249 /*----------------------------------------------------------------------*/
00250 
00251 /** The RA Library. 
00252  *
00253  * A vtable structure which encapsulates all the functionality of a
00254  * particular repository-access implementation.
00255  *
00256  * Note: libsvn_client will keep an array of these objects,
00257  * representing all RA libraries that it has simultaneously loaded
00258  * into memory.  Depending on the situation, the client can look
00259  * through this array and find the appropriate implementation it
00260  * needs.
00261  */
00262 typedef struct svn_ra_plugin_t
00263 {
00264   /** The proper name of the RA library, (like "ra_dav" or "ra_local") */
00265   const char *name;         
00266   
00267   /** Short doc string printed out by `svn --version` */
00268   const char *description;
00269 
00270   /* The vtable hooks */
00271   
00272   /** Open a repository session to @a repos_url.  Return an opaque object
00273    * representing this session in @a *session_baton, allocated in @a pool.
00274    *
00275    * @a callbacks/@a callback_baton is a table of callbacks provided by the
00276    * client; see @c svn_ra_callbacks_t above.
00277    *
00278    * @a config is a hash mapping <tt>const char *</tt> keys to 
00279    * @c svn_config_t * values.  For example, the @c svn_config_t for the 
00280    * "~/.subversion/config" file is under the key "config".
00281    *
00282    * All RA requests require a @a session_baton; they will continue to
00283    * use @a pool for memory allocation.
00284    */
00285   svn_error_t *(*open) (void **session_baton,
00286                         const char *repos_URL,
00287                         const svn_ra_callbacks_t *callbacks,
00288                         void *callback_baton,
00289                         apr_hash_t *config,
00290                         apr_pool_t *pool);
00291 
00292   /** Get the latest revision number from the repository. This is
00293    * useful for the `svn status' command.  :)
00294    *
00295    * Use @a pool for memory allocation.
00296    */
00297   svn_error_t *(*get_latest_revnum) (void *session_baton,
00298                                      svn_revnum_t *latest_revnum,
00299                                      apr_pool_t *pool);
00300 
00301   /** Get the latest revision number at time @a tm.
00302    *
00303    * Use @a pool for memory allocation.
00304    */
00305   svn_error_t *(*get_dated_revision) (void *session_baton,
00306                                       svn_revnum_t *revision,
00307                                       apr_time_t tm,
00308                                       apr_pool_t *pool);
00309 
00310   /** Set the property @a name to @a value on revision @a rev.
00311    *
00312    * If @a value is @c NULL, delete the named revision property.
00313    *
00314    * Please note that properties attached to revisions are **unversioned**.
00315    *
00316    * Use @a pool for memory allocation.
00317    */
00318   svn_error_t *(*change_rev_prop) (void *session_baton,
00319                                    svn_revnum_t rev,
00320                                    const char *name,
00321                                    const svn_string_t *value,
00322                                    apr_pool_t *pool);
00323 
00324   /** Set @a *props to the list of unversioned properties attached to
00325    * revision @a rev.  The hash maps (<tt>const char *</tt>) names to
00326    * (<tt>@c svn_string_t *</tt>) values.
00327    *
00328    * Use @a pool for memory allocation.
00329    */
00330   svn_error_t *(*rev_proplist) (void *session_baton,
00331                                 svn_revnum_t rev,
00332                                 apr_hash_t **props,
00333                                 apr_pool_t *pool);
00334 
00335   /** Set @a *value to the value of unversioned property @a name attached to
00336    * revision @a rev.  If @a rev has no property by that name, set @a *value 
00337    * to @c NULL.
00338    *
00339    * Use @a pool for memory allocation.
00340    */
00341   svn_error_t *(*rev_prop) (void *session_baton,
00342                             svn_revnum_t rev,
00343                             const char *name,
00344                             svn_string_t **value,
00345                             apr_pool_t *pool);
00346                                    
00347   /** Set @a *editor and @a *edit_baton to an editor for committing changes
00348    * to the repository, using @a log_msg as the log message.  The
00349    * revisions being committed against are passed to the editor
00350    * functions, starting with the rev argument to @c open_root.  The path
00351    * root of the commit is in the @a session_baton's url.
00352    *
00353    * These three functions all share @c close_baton:
00354    *
00355    *   * @c get_func is used by the RA layer to fetch any WC properties
00356    *     during the commit.
00357    *
00358    *   * @c set_func is used by the RA layer to set any WC properties,
00359    *     after the commit completes. 
00360    *
00361    *   * @c close_func is used by the RA layer to bump the revisions of
00362    *     each committed item, after the commit completes.  It may be
00363    *     called multiple times.
00364    *
00365    * Any of these functions may be @c NULL.
00366    *
00367    * Before @c close_edit returns, but after the commit has succeeded,
00368    * it will invoke @a callback with the new revision number, the
00369    * commit date (as a <tt>const char *</tt>), commit author (as a
00370    * <tt>const char *</tt>), and @a callback_baton as arguments.  If
00371    * @a callback returns an error, that error will be returned from @c
00372    * close_edit, otherwise @c close_edit will return successfully
00373    * (unless it encountered an error before invoking @a callback).
00374    *
00375    * The callback will not be called if the commit was a no-op
00376    * (i.e. nothing was committed);
00377    *
00378    * The caller may not perform any RA operations using
00379    * @a session_baton before finishing the edit.
00380    * 
00381    * Use @a pool for memory allocation.
00382    */
00383   svn_error_t *(*get_commit_editor) (void *session_baton,
00384                                      const svn_delta_editor_t **editor,
00385                                      void **edit_baton,
00386                                      const char *log_msg,
00387                                      svn_commit_callback_t callback,
00388                                      void *callback_baton,
00389                                      apr_pool_t *pool);
00390 
00391   /** Fetch the contents and properties of file @a path at @a revision.
00392    * Interpret @a path relative to the url in @a session_baton.  Use
00393    * @a pool for all allocations.
00394    *
00395    * If @a revision is @c SVN_INVALID_REVNUM (meaning 'head') and
00396    * @a *fetched_rev is not @c NULL, then this function will set
00397    * @a *fetched_rev to the actual revision that was retrieved.  (Some
00398    * callers want to know, and some don't.) 
00399    *
00400    * If @a stream is non @c NULL, push the contents of the file at @a stream.
00401    *
00402    * If @a props is non @c NULL, set @a *props to contain the properties of 
00403    * the file.  This means *all* properties: not just ones controlled by
00404    * the user and stored in the repository fs, but non-tweakable ones
00405    * generated by the SCM system itself (e.g. 'wcprops', 'entryprops',
00406    * etc.)  The keys are <tt>const char *</tt>, values are 
00407    * <tt>@c svn_string_t *</tt>.
00408    *
00409    * The stream handlers for @a stream may not perform any RA
00410    * operations using @a session_baton.
00411    */
00412   svn_error_t *(*get_file) (void *session_baton,
00413                             const char *path,
00414                             svn_revnum_t revision,
00415                             svn_stream_t *stream,
00416                             svn_revnum_t *fetched_rev,
00417                             apr_hash_t **props,
00418                             apr_pool_t *pool);
00419 
00420   /** If @a dirents is non @c NULL, set @a *dirents to contain all the entries
00421    * of directory @a path at @a revision.  The keys of @a dirents will be 
00422    * entry names (<tt>const char *</tt>), and the values dirents 
00423    * (<tt>@c svn_dirent_t *</tt>).  Use @a pool for all allocations.
00424    *
00425    * @a path is interpreted relative to the url in @a session_baton.  
00426    *
00427    * If @a revision is @c SVN_INVALID_REVNUM (meaning 'head') and
00428    * @a *fetched_rev is not @c NULL, then this function will set
00429    * @a *fetched_rev to the actual revision that was retrieved.  (Some
00430    * callers want to know, and some don't.) 
00431    *
00432    * If @a props is non @c NULL, set @a *props to contain the properties of 
00433    * the directory.  This means *all* properties: not just ones controlled by
00434    * the user and stored in the repository fs, but non-tweakable ones
00435    * generated by the SCM system itself (e.g. 'wcprops', 'entryprops',
00436    * etc.)  The keys are <tt>const char *</tt>, values are 
00437    * <tt>@c svn_string_t *</tt>.
00438    */
00439   svn_error_t *(*get_dir) (void *session_baton,
00440                            const char *path,
00441                            svn_revnum_t revision,
00442                            apr_hash_t **dirents,
00443                            svn_revnum_t *fetched_rev,
00444                            apr_hash_t **props,
00445                            apr_pool_t *pool);
00446 
00447   /** Ask the network layer to update a working copy.
00448    *
00449    * The client initially provides an @a update_editor/@a baton to the 
00450    * RA layer; this editor contains knowledge of where the change will
00451    * begin in the working copy (when @c open_root() is called).
00452    *
00453    * In return, the client receives a @a reporter/@a report_baton. The
00454    * client then describes its working-copy revision numbers by making
00455    * calls into the @a reporter structure; the RA layer assumes that all
00456    * paths are relative to the URL used to create @a session_baton.
00457    *
00458    * When finished, the client calls @a reporter->finish_report().  The
00459    * RA layer then does a complete drive of @a update_editor, ending with
00460    * @c close_edit(), to update the working copy.
00461    *
00462    * @a update_target is an optional single path component will restrict
00463    * the scope of things affected by the update to an entry in the
00464    * directory represented by the @a session_baton's URL, or empty if the
00465    * entire directory is meant to be updated.
00466    *
00467    * The working copy will be updated to @a revision_to_update_to, or the
00468    * "latest" revision if this arg is invalid.
00469    *
00470    * The caller may not perform any RA operations using
00471    * @a session_baton before finishing the report, and may not perform
00472    * any RA operations using @a session_baton from within the editing
00473    * operations of @a update_editor.
00474    *
00475    * Use @a pool for memory allocation.
00476    */
00477   svn_error_t *(*do_update) (void *session_baton,
00478                              const svn_ra_reporter_t **reporter,
00479                              void **report_baton,
00480                              svn_revnum_t revision_to_update_to,
00481                              const char *update_target,
00482                              svn_boolean_t recurse,
00483                              const svn_delta_editor_t *update_editor,
00484                              void *update_baton,
00485                              apr_pool_t *pool);
00486 
00487   /** Ask the network layer to 'switch' a working copy to a new
00488    * @a switch_url;  it's another form of @c do_update().
00489    *
00490    * The client initially provides an @a switch_editor/@a baton to the RA
00491    * layer; this editor contains knowledge of where the change will
00492    * begin in the working copy (when @c open_root() is called). 
00493    *
00494    * In return, the client receives a @a reporter/@a report_baton. The
00495    * client then describes its working-copy revision numbers by making
00496    * calls into the @a reporter structure; the RA layer assumes that all
00497    * paths are relative to the URL used to create @a session_baton.
00498    *
00499    * When finished, the client calls @a reporter->finish_report().  The
00500    * RA layer then does a complete drive of @a switch_editor, ending with
00501    * @c close_edit(), to switch the working copy.
00502    *
00503    * @a switch_target is an optional single path component will restrict
00504    * the scope of things affected by the switch to an entry in the
00505    * directory represented by the @a session_baton's URL, or empty if the
00506    * entire directory is meant to be switched.
00507    *
00508    * The working copy will be switched to @a revision_to_switch_to, or the
00509    * "latest" revision if this arg is invalid.
00510    *
00511    * The caller may not perform any RA operations using
00512    * @a session_baton before finishing the report, and may not perform
00513    * any RA operations using @a session_baton from within the editing
00514    * operations of @a switch_editor.
00515    *
00516    * Use @a pool for memory allocation.
00517    */
00518   svn_error_t *(*do_switch) (void *session_baton,
00519                              const svn_ra_reporter_t **reporter,
00520                              void **report_baton,
00521                              svn_revnum_t revision_to_switch_to,
00522                              const char *switch_target,
00523                              svn_boolean_t recurse,
00524                              const char *switch_url,
00525                              const svn_delta_editor_t *switch_editor,
00526                              void *switch_baton,
00527                              apr_pool_t *pool);
00528 
00529   /** Ask the network layer to describe the status of a working copy
00530    * with respect to @a revision of the repository (or HEAD, if @a
00531    * revision is invalid).
00532    *
00533    * The client initially provides an @a status_editor/@a baton to the RA
00534    * layer; this editor contains knowledge of where the change will
00535    * begin in the working copy (when @c open_root() is called).
00536    *
00537    * In return, the client receives a @a reporter/@a report_baton. The
00538    * client then describes its working-copy revision numbers by making
00539    * calls into the @a reporter structure; the RA layer assumes that all
00540    * paths are relative to the URL used to create @a session_baton.
00541    *
00542    * When finished, the client calls @a reporter->finish_report(). The RA
00543    * layer then does a complete drive of @a status_editor, ending with
00544    * @c close_edit(), to report, essentially, what would be modified in
00545    * the working copy were the client to call @c do_update().
00546    * @a status_target is an optional single path component will restrict
00547    * the scope of the status report to an entry in the directory
00548    * represented by the @a session_baton's URL, or empty if the entire
00549    * directory is meant to be examined.
00550    *
00551    * The caller may not perform any RA operations using
00552    * @a session_baton before finishing the report, and may not perform
00553    * any RA operations using @a session_baton from within the editing
00554    * operations of @a status_editor.
00555    *
00556    * Use @a pool for memory allocation.
00557    */
00558   svn_error_t *(*do_status) (void *session_baton,
00559                              const svn_ra_reporter_t **reporter,
00560                              void **report_baton,
00561                              const char *status_target,
00562                              svn_revnum_t revision,
00563                              svn_boolean_t recurse,
00564                              const svn_delta_editor_t *status_editor,
00565                              void *status_baton,
00566                              apr_pool_t *pool);
00567 
00568 
00569   /** Ask the network layer to 'diff' a working copy against @a versus_url;
00570    * it's another form of @c do_update().
00571    *
00572    *    [Please note: this function cannot be used to diff a single
00573    *    file, only a working copy directory.  See the do_switch()
00574    *    function for more details.]
00575    *
00576    * The client initially provides a @a diff_editor/@a baton to the RA
00577    * layer; this editor contains knowledge of where the common diff
00578    * root is in the working copy (when @c open_root() is called). 
00579    *
00580    * In return, the client receives a @a reporter/@a report_baton. The
00581    * client then describes its working-copy revision numbers by making
00582    * calls into the @a reporter structure; the RA layer assumes that all
00583    * paths are relative to the URL used to create @a session_baton.
00584    *
00585    * When finished, the client calls @a reporter->finish_report().  The
00586    * RA layer then does a complete drive of @a diff_editor, ending with
00587    * @c close_edit(), to transmit the diff.
00588    *
00589    * @a diff_target is an optional single path component will restrict
00590    * the scope of the diff to an entry in the directory represented by
00591    * the @a session_baton's URL, or empty if the entire directory is 
00592    * meant to be one of the diff paths.
00593    *
00594    * The working copy will be diffed against @a versus_url as it exists
00595    * in revision @a revision, or as it is in head if @a revision is
00596    * @c SVN_INVALID_REVNUM.
00597    *
00598    * Use @a ignore_ancestry to control whether or not items being
00599    * diffed will be checked for relatedness first.  Unrelated items
00600    * are typically transmitted to the editor as a deletion of one thing
00601    * and the addition of another, but if this flag is @c TRUE,
00602    * unrelated items will be diffed as if they were related.
00603    *
00604    * The caller may not perform any RA operations using
00605    * @a session_baton before finishing the report, and may not perform
00606    * any RA operations using @a session_baton from within the editing
00607    * operations of @a diff_editor.
00608    *
00609    * Use @a pool for memory allocation.
00610    */
00611   svn_error_t *(*do_diff) (void *session_baton,
00612                            const svn_ra_reporter_t **reporter,
00613                            void **report_baton,
00614                            svn_revnum_t revision,
00615                            const char *diff_target,
00616                            svn_boolean_t recurse,
00617                            svn_boolean_t ignore_ancestry,
00618                            const char *versus_url,
00619                            const svn_delta_editor_t *diff_editor,
00620                            void *diff_baton,
00621                            apr_pool_t *pool);
00622 
00623   /** Invoke @a receiver with @a receiver_baton on each log message from
00624    * @a start to @a end.  @a start may be greater or less than @a end; 
00625    * this just controls whether the log messages are processed in descending 
00626    * or ascending revision number order.
00627    *
00628    * If @a start or @a end is @c SVN_INVALID_REVNUM, it defaults to youngest.
00629    *
00630    * If @a paths is non-null and has one or more elements, then only show
00631    * revisions in which at least one of @a paths was changed (i.e., if
00632    * file, text or props changed; if dir, props changed or an entry
00633    * was added or deleted).  Each path is an <tt>const char *</tt>, relative 
00634    * to the session's common parent.
00635    *
00636    * If @a discover_changed_paths, then each call to receiver passes a
00637    * <tt>const apr_hash_t *</tt> for the receiver's @a changed_paths argument;
00638    * the hash's keys are all the paths committed in that revision.
00639    * Otherwise, each call to receiver passes null for @a changed_paths.
00640    *
00641    * If @a strict_node_history is set, copy history will not be traversed
00642    * (if any exists) when harvesting the revision logs for each path.
00643    *
00644    * If any invocation of @a receiver returns error, return that error
00645    * immediately and without wrapping it.
00646    *
00647    * If @a start or @a end is a non-existent revision, return the error
00648    * @c SVN_ERR_FS_NO_SUCH_REVISION, without ever invoking @a receiver.
00649    *
00650    * See also the documentation for @c svn_log_message_receiver_t.
00651    *
00652    * The caller may not invoke any RA operations using
00653    * @a session_baton from within @a receiver.
00654    *
00655    * Use @a pool for memory allocation.
00656    */
00657   svn_error_t *(*get_log) (void *session_baton,
00658                            const apr_array_header_t *paths,
00659                            svn_revnum_t start,
00660                            svn_revnum_t end,
00661                            svn_boolean_t discover_changed_paths,
00662                            svn_boolean_t strict_node_history,
00663                            svn_log_message_receiver_t receiver,
00664                            void *receiver_baton,
00665                            apr_pool_t *pool);
00666 
00667   /* Yoshiki Hayashi <yoshiki@xemacs.org> points out that a more
00668      generic way to support 'discover_changed_paths' in logs would be
00669      to have these two functions:
00670     
00671          svn_error_t *(*get_rev_prop) (void *session_baton,
00672                                        svn_string_t **value,
00673                                        svn_string_t *name,
00674                                        svn_revnum_t revision);
00675     
00676          svn_error_t *(get_changed_paths) (void *session_baton,
00677                                            apr_array_header_t **changed_paths,
00678                                            svn_revnum_t revision);
00679     
00680      Although log requests are common enough to deserve special
00681      support (to optimize network usage), these two more generic
00682      functions are still good ideas.  Don't want to implement them
00683      right now, as am concentrating on the log functionality, but we
00684      will probably want them eventually, hence this start block.  */
00685 
00686 
00687   /** Set @a *kind to node kind associated with @a path at @a revision.  
00688    * If @a path does not exist under @a revision, set @a *kind to 
00689    * @c svn_node_none.  @a path is relative to the session's parent URL.
00690    *
00691    * Use @a pool for memory allocation.
00692    */
00693   svn_error_t *(*check_path) (void *session_baton,
00694                               const char *path,
00695                               svn_revnum_t revision,
00696                               svn_node_kind_t *kind,
00697                               apr_pool_t *pool);
00698 
00699   /** Set @a *uuid to the repository's UUID.
00700    *
00701    * NOTE: the UUID has the same lifetime as the session_baton. 
00702    *
00703    * Use @a pool for temporary memory allocation.
00704    */
00705   svn_error_t *(*get_uuid) (void *session_baton,
00706                             const char **uuid,
00707                             apr_pool_t *pool);
00708 
00709   /** Set @a *url to the repository's root URL.  The value
00710    * will not include a trailing '/'.
00711    *
00712    * NOTE: the URL has the same lifetime as the session_baton. 
00713    *
00714    * Use @a pool for temporary memory allocation.
00715    */
00716   svn_error_t *(*get_repos_root) (void *session_baton,
00717                                   const char **url,
00718                                   apr_pool_t *pool);
00719 
00720 } svn_ra_plugin_t;
00721 
00722 
00723 /**
00724  * libsvn_client will be responsible for loading each RA DSO it needs.
00725  * However, all "ra_FOO" implementations *must* export a function named
00726  * @c svn_ra_FOO_init() of type @c svn_ra_init_func_t.
00727  *
00728  * When called by libsvn_client, this routine adds an entry (or
00729  * entries) to the hash table for any URL schemes it handles. The hash
00730  * value must be of type (<tt>@c svn_ra_plugin_t *</tt>). @a pool is a 
00731  * pool for allocating configuration / one-time data.
00732  *
00733  * This type is defined to use the "C Calling Conventions" to ensure that
00734  * abi_version is the first parameter. The RA plugin must check that value
00735  * before accessing the other parameters.
00736  *
00737  * ### need to force this to be __cdecl on Windows... how??
00738  */
00739 typedef svn_error_t *(*svn_ra_init_func_t) (int abi_version,
00740                                             apr_pool_t *pool,
00741                                             apr_hash_t *hash);
00742 
00743 /** The current ABI (Application Binary Interface) version for the
00744  * RA plugin model. This version number will change when the ABI
00745  * between the SVN core (e.g. libsvn_client) and the RA plugin changes.
00746  *
00747  * An RA plugin should verify that the passed version number is acceptable
00748  * before accessing the rest of the parameters, and before returning any
00749  * information.
00750  *
00751  * It is entirely acceptable for an RA plugin to accept multiple ABI
00752  * versions. It can simply interpret the parameters based on the version,
00753  * and it can return different plugin structures.
00754  *
00755  *
00756  * <pre>
00757  * VSN  DATE        REASON FOR CHANGE
00758  * ---  ----------  ------------------------------------------------
00759  *   1  2001-02-17  Initial revision.
00760  * </pre>
00761  */
00762 #define SVN_RA_ABI_VERSION      1
00763 
00764 
00765 /* Public RA implementations: ADD MORE HERE as necessary. */
00766 
00767 /** initialize libsvn_ra_dav. */
00768 svn_error_t * svn_ra_dav_init (int abi_version,
00769                                apr_pool_t *pool,
00770                                apr_hash_t *hash);
00771 
00772 /** initialize libsvn_ra_local. */
00773 svn_error_t * svn_ra_local_init (int abi_version,
00774                                  apr_pool_t *pool,
00775                                  apr_hash_t *hash);
00776 
00777 /** initialize libsvn_ra_svn. */
00778 svn_error_t * svn_ra_svn_init (int abi_version,
00779                                apr_pool_t *pool,
00780                                apr_hash_t *hash);
00781 
00782 
00783 
00784 /* Public Interfaces */
00785 
00786 /** Initialize the RA libraries.
00787  *
00788  * Every user of the RA layer *must* call this routine and hold on to
00789  * the @a ra_baton returned.  This baton contains all known methods of
00790  * accessing a repository, for use within most @c svn_client_* routines.
00791  */
00792 svn_error_t * svn_ra_init_ra_libs (void **ra_baton, apr_pool_t *pool);
00793 
00794 
00795 /** Return an RA vtable-@a library (already within @a ra_baton) which can
00796  * handle URL.  A number of svn_client_* routines will call this
00797  * internally, but client apps might use it too.  
00798  *
00799  * For reference, note that according to W3 RFC 1738, a valid URL is
00800  * of the following form:
00801  *
00802  *   scheme://<user>:<password>\@<host>:<port>/<url-path> 
00803  *
00804  * Common URLs are as follows:
00805  *
00806  *   http://subversion.tigris.org/index.html
00807  *   file:///home/joeuser/documents/resume.txt
00808  *
00809  * Of interest is the file URL schema, which takes the form
00810  * file://<host>/<path>, where <host> and <path> are optional.  The 
00811  * `/' between <host> and <path> is NOT part of path, yet the RFC doesn't
00812  * specify how <path> should be formatted.  SVN will count on the
00813  * portability layer to be able to handle the specific formatting of
00814  * the <path> on a per-system basis.
00815  */
00816 svn_error_t *svn_ra_get_ra_library (svn_ra_plugin_t **library,
00817                                     void *ra_baton,
00818                                     const char *url,
00819                                     apr_pool_t *pool);
00820 
00821 /** Return a @a *descriptions string (allocated in @a pool) that is a textual
00822  * list of all available RA libraries.
00823  */
00824 svn_error_t *svn_ra_print_ra_libraries (svn_stringbuf_t **descriptions,
00825                                         void *ra_baton,
00826                                         apr_pool_t *pool);
00827 
00828 
00829 
00830 
00831 
00832 #ifdef __cplusplus
00833 }
00834 #endif /* __cplusplus */
00835 
00836 #endif  /* SVN_RA_H */

Generated on Mon Oct 18 17:33:13 2004 for Subversion by doxygen 1.3.5