subversion-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From gst...@apache.org
Subject svn commit: r1330615 - /subversion/trunk/subversion/include/private/svn_ra_private.h
Date Thu, 26 Apr 2012 01:00:15 GMT
Author: gstein
Date: Thu Apr 26 01:00:15 2012
New Revision: 1330615

URL: http://svn.apache.org/viewvc?rev=1330615&view=rev
Log:
Add some documentation for the new stuff in svn_ra_private.

* subversion/include/private/svn_ra_private.h:
  (svn_ra__provide_base_cb_t, svn_ra__provide_props_cb_t,
      svn_ra__get_copysrc_kind_cb_t, svn_ra__get_commit_ev2): update
    and expand docstrings

Modified:
    subversion/trunk/subversion/include/private/svn_ra_private.h

Modified: subversion/trunk/subversion/include/private/svn_ra_private.h
URL: http://svn.apache.org/viewvc/subversion/trunk/subversion/include/private/svn_ra_private.h?rev=1330615&r1=1330614&r2=1330615&view=diff
==============================================================================
--- subversion/trunk/subversion/include/private/svn_ra_private.h (original)
+++ subversion/trunk/subversion/include/private/svn_ra_private.h Thu Apr 26 01:00:15 2012
@@ -137,7 +137,12 @@ svn_ra__register_editor_shim_callbacks(s
 
 /* Using information from BATON, provide the (file's) pristine contents
    for REPOS_RELPATH. They are returned in *CONTENTS, and correspond to
-   *REVISION. These are allocated in RESULT_POOL. SCRATCH_POOL can be used
+   *REVISION.
+
+   If a pristine is not available (ie. a locally-added node), then set
+   *CONTENTS to NULL; *REVISION will not be examined in this case.
+
+   These are allocated in RESULT_POOL. SCRATCH_POOL can be used
    for temporary allocations.  */
 typedef svn_error_t *(*svn_ra__provide_base_cb_t)(
   svn_stream_t **contents,
@@ -149,6 +154,10 @@ typedef svn_error_t *(*svn_ra__provide_b
 
 /* Using information from BATON, provide the pristine properties for
    REPOS_RELPATH. They are returned in *PROPS, and correspond to *REVISION.
+
+   If properties are not available (ie. a locally-added node), then set
+   *PROPS to NULL; *REVISION will not be examined in this case.
+
    The properties are allocated in RESULT_POOL. SCRATCH_POOL can be used
    for temporary allocations.  */
 typedef svn_error_t *(*svn_ra__provide_props_cb_t)(
@@ -160,8 +169,11 @@ typedef svn_error_t *(*svn_ra__provide_p
   apr_pool_t *scratch_pool);
 
 /* Using information from BATON, fetch the kind of REPOS_RELPATH at revision
-   SRC_REVISION, returning it in *KIND. Temporary allocations can be made
-   in SCRATCH_POOL.  */
+   SRC_REVISION, returning it in *KIND.
+
+   If the kind cannot be determined, then set *KIND to svn_kind_unknown.
+
+   Temporary allocations can be made in SCRATCH_POOL.  */
 typedef svn_error_t *(*svn_ra__get_copysrc_kind_cb_t)(
   svn_kind_t *kind,
   void *baton,
@@ -170,14 +182,53 @@ typedef svn_error_t *(*svn_ra__get_copys
   apr_pool_t *scratch_pool);
 
 
-/* ### hand-wave... see svn_ra_get_commit_editor3() for the basics
-   ### of these parameters.  */
+/* Return an Ev2-based editor for performing commits.
+
+   The editor is associated with the given SESSION, and its implied target
+   repository.
+
+   REVPROPS contains all the revision properties that should be stored onto
+   the newly-committed revision. SVN_PROP_REVISION_AUTHOR will be set to
+   the username as determined by the session; overwriting any prior value
+   that may be present in REVPROPS.
+
+   COMMIT_CB/BATON contain the callback to receive post-commit information.
+
+   LOCK_TOKENS should contain all lock tokens necessary to modify paths
+   within the commit. If KEEP_LOCKS is FALSE, then the paths associated
+   with these tokens will be unlocked.
+   ### today, LOCK_TOKENS is session_relpath:token_value. in the future,
+   ### it should be repos_relpath:token_value.
+
+   PROVIDE_BASE_CB is a callback to fetch pristine contents, used to send
+   an svndiff over the wire to the server. This may be NULL, indicating
+   pristine contents are not available (eg. URL-based operations or import).
+
+   PROVIDE_PROPS_CB is a callback to fetch pristine properties, used to
+   send property deltas over the wire to the server. This may be NULL,
+   indicating pristine properties are not available (eg. URL-based operations
+   or an import).
+
+   GET_COPYSRC_KIND_CB is a callback to determine the kind of a copy-source.
+   This is necessary when an Ev2/Ev1 shim is required by the RA provider,
+   in order to determine whether to use delta->add_directory() or the
+   delta->add_file() vtable entry to perform the copy.
+   ### unclear on impact if this is NULL.
+
+   CB_BATON is the baton used/shared by the above three callbacks.
+
+   CANCEL_FUNC/BATON is a standard cancellation function, and is used for
+   the returned Ev2 editor, and possibly other RA-specific operations.
+
+   *EDITOR will be allocated in RESULT_POOL, and all temporary allocations
+   will be performed in SCRATCH_POOL.
+*/
 svn_error_t *
 svn_ra__get_commit_ev2(svn_editor_t **editor,
                        svn_ra_session_t *session,
-                       apr_hash_t *revprop_table,
-                       svn_commit_callback2_t callback,
-                       void *callback_baton,
+                       apr_hash_t *revprops,
+                       svn_commit_callback2_t commit_cb,
+                       void *commit_baton,
                        apr_hash_t *lock_tokens,
                        svn_boolean_t keep_locks,
                        svn_ra__provide_base_cb_t provide_base_cb,



Mime
View raw message