svn_ra.h

linux subdivision ying gai ke yi le ba

   *
   * Use @a ignore_ancestry to control whether or not items being
   * diffed will be checked for relatedness first.  Unrelated items
   * are typically transmitted to the editor as a deletion of one thing
   * and the addition of another, but if this flag is @c TRUE,
   * unrelated items will be diffed as if they were related.
   *
   * The caller may not perform any RA operations using
   * @a session_baton before finishing the report, and may not perform
   * any RA operations using @a session_baton from within the editing
   * operations of @a diff_editor.
   *
   * Use @a pool for memory allocation.
   */
  svn_error_t *(*do_diff) (void *session_baton,
                           const svn_ra_reporter_t **reporter,
                           void **report_baton,
                           svn_revnum_t revision,
                           const char *diff_target,
                           svn_boolean_t recurse,
                           svn_boolean_t ignore_ancestry,
                           const char *versus_url,
                           const svn_delta_editor_t *diff_editor,
                           void *diff_baton,
                           apr_pool_t *pool);

  /** Invoke @a receiver with @a receiver_baton on each log message from
   * @a start to @a end.  @a start may be greater or less than @a end; 
   * this just controls whether the log messages are processed in descending 
   * or ascending revision number order.
   *
   * If @a start or @a end is @c SVN_INVALID_REVNUM, it defaults to youngest.
   *
   * If @a paths is non-null and has one or more elements, then only show
   * revisions in which at least one of @a paths was changed (i.e., if
   * file, text or props changed; if dir, props changed or an entry
   * was added or deleted).  Each path is an <tt>const char *</tt>, relative 
   * to the session's common parent.
   *
   * If @a discover_changed_paths, then each call to receiver passes a
   * <tt>const apr_hash_t *</tt> for the receiver's @a changed_paths argument;
   * the hash's keys are all the paths committed in that revision.
   * Otherwise, each call to receiver passes null for @a changed_paths.
   *
   * If @a strict_node_history is set, copy history will not be traversed
   * (if any exists) when harvesting the revision logs for each path.
   *
   * If any invocation of @a receiver returns error, return that error
   * immediately and without wrapping it.
   *
   * If @a start or @a end is a non-existent revision, return the error
   * @c SVN_ERR_FS_NO_SUCH_REVISION, without ever invoking @a receiver.
   *
   * See also the documentation for @c svn_log_message_receiver_t.
   *
   * The caller may not invoke any RA operations using
   * @a session_baton from within @a receiver.
   *
   * Use @a pool for memory allocation.
   */
  svn_error_t *(*get_log) (void *session_baton,
                           const apr_array_header_t *paths,
                           svn_revnum_t start,
                           svn_revnum_t end,
                           svn_boolean_t discover_changed_paths,
                           svn_boolean_t strict_node_history,
                           svn_log_message_receiver_t receiver,
                           void *receiver_baton,
                           apr_pool_t *pool);

  /* Yoshiki Hayashi <[e-mail]> points out that a more
     generic way to support 'discover_changed_paths' in logs would be
     to have these two functions:
    
         svn_error_t *(*get_rev_prop) (void *session_baton,
                                       svn_string_t **value,
                                       svn_string_t *name,
                                       svn_revnum_t revision);
    
         svn_error_t *(get_changed_paths) (void *session_baton,
                                           apr_array_header_t **changed_paths,
                                           svn_revnum_t revision);
    
     Although log requests are common enough to deserve special
     support (to optimize network usage), these two more generic
     functions are still good ideas.  Don't want to implement them
     right now, as am concentrating on the log functionality, but we
     will probably want them eventually, hence this start block.  */


  /** Set @a *kind to node kind associated with @a path at @a revision.  
   * If @a path does not exist under @a revision, set @a *kind to 
   * @c svn_node_none.  @a path is relative to the session's parent URL.
   *
   * Use @a pool for memory allocation.
   */
  svn_error_t *(*check_path) (void *session_baton,
                              const char *path,
                              svn_revnum_t revision,
                              svn_node_kind_t *kind,
                              apr_pool_t *pool);

  /** Set @a *uuid to the repository's UUID.
   *
   * NOTE: the UUID has the same lifetime as the session_baton. 
   *
   * Use @a pool for temporary memory allocation.
   */
  svn_error_t *(*get_uuid) (void *session_baton,
                            const char **uuid,
                            apr_pool_t *pool);

  /** Set @a *url to the repository's root URL.  The value
   * will not include a trailing '/'.  The returned URL is guaranteed
   * to be a prefix of the session's parent URL.
   *
   * NOTE: the URL has the same lifetime as the session_baton. 
   *
   * Use @a pool for temporary memory allocation.
   */
  svn_error_t *(*get_repos_root) (void *session_baton,
                                  const char **url,
                                  apr_pool_t *pool);

  /** @since New in 1.1.
   *
   * Set @a *locations to the locations at the repository revisions
   * @a location_revisions of the file @a path present at the repository in
   * revision @a peg_revision.  @a path is a path relative to the URL to which
   * the RA session was opened. @a location_revisions is an array of
   * svn_revnum_t's. @a *locations will be a mapping from the revisions to
   * their appropriate absolute paths.  If the file doesn't exist in a
   * in location_revision, that revision will be ignored.
   *
   * NOTE: For servers older than 1.1, this function will return an
   * SVN_ERR_RA_NOT_IMPLEMENTED error.
   *
   * Use @a pool for all allocations.
   *
   * NOTE: This functionality is not available in pre-1.1 servers.  If the
   * server doesn't implement it, an @c SVN_ERR_RA_NOT_IMPLEMENTED error is
   * returned.
   */
  svn_error_t *(*get_locations) (void *session_baton,
                                 apr_hash_t **locations,
                                 const char *path,
                                 svn_revnum_t peg_revision,
                                 apr_array_header_t *location_revisions,
                                 apr_pool_t *pool);

  /** @since New in 1.1.
   * Retrieve a subset of the interesting revisions of a file @a path
   * as seen in revision @a end.  Invoke @a handler with @a handler_baton
   * as its first argument for each such revision.  @a sesson_baton is
   * an open RA session.  @a pool is used for all allocations.  See
   * @c svn_fs_history_prev for a discussion of interesting revisions.
   *
   * If there is an interesting revision of the file that is less than or
   * equal to start, the iteration will start at that revision.  Else, the
   * iteration will start at the first revision of the file in the repository,
   * whic has to be less than or equal to end.  Note that if the function
   * succeeds, @a handler will have been called at least once.
   *
   * In a series of calls, the file contents for the first interesting revision
   * will be provided as a text delta against the empty file.  In the following
   * calls, the delta will be against the contents for the previous call.
   *
   * NOTE: This functionality is not available in pre-1.1 servers.  If the
   * server doesn't implement it, an @c SVN_ERR_RA_NOT_IMPLEMENTED error is
   * returned. */
  svn_error_t *(*get_file_revs) (void *session_baton,
                                 const char *path,
                                 svn_revnum_t start,
                                 svn_revnum_t end,
                                 svn_ra_file_rev_handler_t handler,
                                 void *handler_baton,
                                 apr_pool_t *pool);

  /** @since New in 1.1.
   * Return the plugin's version information.
   */
  /* FIXME: This is broken. The get_version function should be at the
     beginning of the vtable, just after the description, and should
     not move even between major releases (see, e.g., the FS library
     vtable). That's the only safe way for the RA loader to retreive
     the plugin's version regardless of ABI changes. Obviously we
     can't fix this before 2.0, and the fix will cause undetectable
     ABI breakage. */
  const svn_version_t *(*get_version) (void);
} svn_ra_plugin_t;


/**
 * libsvn_client will be responsible for loading each RA DSO it needs.
 * However, all "ra_FOO" implementations *must* export a function named
 * @c svn_ra_FOO_init() of type @c svn_ra_init_func_t.
 *
 * When called by libsvn_client, this routine adds an entry (or
 * entries) to the hash table for any URL schemes it handles. The hash
 * value must be of type (<tt>@c svn_ra_plugin_t *</tt>). @a pool is a 
 * pool for allocating configuration / one-time data.
 *
 * This type is defined to use the "C Calling Conventions" to ensure that
 * abi_version is the first parameter. The RA plugin must check that value
 * before accessing the other parameters.
 *
 * ### need to force this to be __cdecl on Windows... how??
 */
typedef svn_error_t *(*svn_ra_init_func_t) (int abi_version,
                                            apr_pool_t *pool,
                                            apr_hash_t *hash);

/** The current ABI (Application Binary Interface) version for the
 * RA plugin model. This version number will change when the ABI
 * between the SVN core (e.g. libsvn_client) and the RA plugin changes.
 *
 * An RA plugin should verify that the passed version number is acceptable
 * before accessing the rest of the parameters, and before returning any
 * information.
 *
 * It is entirely acceptable for an RA plugin to accept multiple ABI
 * versions. It can simply interpret the parameters based on the version,
 * and it can return different plugin structures.
 *
 *
 * <pre>
 * VSN  DATE        REASON FOR CHANGE
 * ---  ----------  ------------------------------------------------
 *   1  2001-02-17  Initial revision.
 *   2  2004-06-29  Preparing for svn 1.1, which adds new RA vtable funcs.
 * </pre>
 *
 * @deprecated Provided for backward compatibility with the 1.0 API.
 */
#define SVN_RA_ABI_VERSION      2


/* Public RA implementations: ADD MORE HERE as necessary. */

/** initialize libsvn_ra_dav. */
svn_error_t * svn_ra_dav_init (int abi_version,
                               apr_pool_t *pool,
                               apr_hash_t *hash);

/** initialize libsvn_ra_local. */
svn_error_t * svn_ra_local_init (int abi_version,
                                 apr_pool_t *pool,
                                 apr_hash_t *hash);

/** initialize libsvn_ra_svn. */
svn_error_t * svn_ra_svn_init (int abi_version,
                               apr_pool_t *pool,
                               apr_hash_t *hash);



/* Public Interfaces */

/** Initialize the RA libraries.
 *
 * Every user of the RA layer *must* call this routine and hold on to
 * the @a ra_baton returned.  This baton contains all known methods of
 * accessing a repository, for use within most @c svn_client_* routines.
 */
svn_error_t * svn_ra_init_ra_libs (void **ra_baton, apr_pool_t *pool);


/** Return an RA vtable-@a library (already within @a ra_baton) which can
 * handle URL.  A number of svn_client_* routines will call this
 * internally, but client apps might use it too.  
 *
 * For reference, note that according to W3 RFC 1738, a valid URL is
 * of the following form:
 *
 *   scheme://\<user\>:\<password\>\@\<host\>:\<port\>/\<url-path\> 
 *
 * Common URLs are as follows:
 *
 *   http://subversion.tigris.org/index.html
 *   file:///home/joeuser/documents/resume.txt
 *
 * Of interest is the file URL schema, which takes the form
 * file://\<host\>/\<path\>, where \<host\> and \<path\> are optional.  The 
 * `/' between \<host\> and \<path\> is NOT part of path, yet the RFC doesn't
 * specify how \<path\> should be formatted.  SVN will count on the
 * portability layer to be able to handle the specific formatting of
 * the \<path\> on a per-system basis.
 */
svn_error_t *svn_ra_get_ra_library (svn_ra_plugin_t **library,
                                    void *ra_baton,
                                    const char *url,
                                    apr_pool_t *pool);

/** Return a @a *descriptions string (allocated in @a pool) that is a textual
 * list of all available RA libraries.
 */
svn_error_t *svn_ra_print_ra_libraries (svn_stringbuf_t **descriptions,
                                        void *ra_baton,
                                        apr_pool_t *pool);





#ifdef __cplusplus
}
#endif /* __cplusplus */

#endif  /* SVN_RA_H */