| /* |
| * svn_ra.h : structures related to repository access |
| * |
| * ==================================================================== |
| * Copyright (c) 2000-2002 CollabNet. All rights reserved. |
| * |
| * This software is licensed as described in the file COPYING, which |
| * you should have received as part of this distribution. The terms |
| * are also available at http://subversion.tigris.org/license-1.html. |
| * If newer versions of this license are posted there, you may use a |
| * newer version instead, at your option. |
| * |
| * This software consists of voluntary contributions made by many |
| * individuals. For exact contribution history, see the revision |
| * history and logs, available at http://subversion.tigris.org/. |
| * ==================================================================== |
| */ |
| |
| |
| |
| |
| #ifndef SVN_RA_H |
| #define SVN_RA_H |
| |
| #include <apr_pools.h> |
| #include <apr_tables.h> |
| |
| #include "svn_error.h" |
| #include "svn_delta.h" |
| |
| #ifdef __cplusplus |
| extern "C" { |
| #endif /* __cplusplus */ |
| |
| |
| /*----------------------------------------------------------------------*/ |
| |
| /* Misc. declarations */ |
| |
| /* This is a function type which allows the RA layer to fetch working |
| copy (WC) properties. |
| |
| The BATON is provided along with the function pointer and should |
| be passed back in. This will be the CALLBACK_BATON or the CLOSE_BATON |
| as appropriate. |
| |
| PATH is relative to the "root" of the session, defined by the REPOS_URL |
| passed to the RA->open() vtable call. |
| |
| NAME is the name of the property to fetch. If the property is present, |
| then it is returned in VALUE. Otherwise, *VALUE is set to NULL. |
| */ |
| typedef svn_error_t *(*svn_ra_get_wc_prop_func_t) (void *baton, |
| const char *relpath, |
| const char *name, |
| const svn_string_t **value, |
| apr_pool_t *pool); |
| |
| /* This is a function type which allows the RA layer to store working |
| copy (WC) properties. |
| |
| See the comments for svn_ra_get_wc_prop_func_t to for BATON, PATH, and |
| NAME. |
| |
| The VALUE is the value that will be stored for the property. |
| */ |
| typedef svn_error_t *(*svn_ra_set_wc_prop_func_t) (void *baton, |
| const char *path, |
| const char *name, |
| const svn_string_t *value, |
| apr_pool_t *pool); |
| |
| /* A function type for retrieving the youngest revision from a repos. */ |
| typedef svn_error_t *(*svn_ra_get_latest_revnum_func_t) |
| (void *session_baton, |
| svn_revnum_t *latest_revnum); |
| |
| /*----------------------------------------------------------------------*/ |
| |
| /* The update Reporter */ |
| |
| /* A vtable structure which allows a working copy to describe a |
| subset (or possibly all) of its working-copy to an RA layer. */ |
| |
| typedef struct svn_ra_reporter_t |
| { |
| /* Describe a working copy PATH as being at a particular REVISION; |
| this will *override* any previous set_path() calls made on parent |
| paths. PATH is relative to the URL specified in open(). */ |
| svn_error_t *(*set_path) (void *report_baton, |
| const char *path, |
| svn_revnum_t revision); |
| |
| /* Describing a working copy PATH as missing. */ |
| svn_error_t *(*delete_path) (void *report_baton, |
| const char *path); |
| |
| /* WC calls this when the state report is finished; any directories |
| or files not explicitly `set' above are assumed to be at the |
| baseline revision originally passed into do_update(). */ |
| svn_error_t *(*finish_report) (void *report_baton); |
| |
| /* If an error occurs during a report, this routine should cause the |
| filesystem transaction to be aborted & cleaned up. */ |
| svn_error_t *(*abort_report) (void *report_baton); |
| |
| } svn_ra_reporter_t; |
| |
| /*----------------------------------------------------------------------*/ |
| |
| /*** Authentication ***/ |
| |
| /* This is the 2nd draft of client-side authentication; in the first |
| draft, the client presumed to be in control of selecting auth |
| methods and then "pushing" data at the RA layer. In this draft, |
| the RA layer is presumed to be in control; as server challenges are |
| made, it "pulls" data from the client via callbacks. */ |
| |
| |
| /* List all known authenticator objects (protocols) here. */ |
| enum svn_ra_auth_method |
| { |
| svn_ra_auth_username, |
| svn_ra_auth_simple_password |
| }; |
| /* ### someday add other protocols here: PRIVATE_KEY, CERT, etc. */ |
| |
| |
| /* Authenticators: these are small "protocol" vtables that are |
| implemented by libsvn_client, but are driven by the RA layer. |
| |
| (Because they're related to authentication, we define them here in |
| svn_ra.h) |
| |
| The RA layer is challenged by the server, and then fetches one of |
| these vtables in order to retrieve the necessary authentication |
| info from the client. */ |
| |
| |
| /* A protocol which only needs a username. (used by ra_local) |
| (matches type svn_ra_auth_username above.) */ |
| typedef struct svn_ra_username_authenticator_t |
| { |
| /* Get a username from the client. */ |
| svn_error_t *(*get_username) (char **username, |
| void *auth_baton, |
| svn_boolean_t force_prompt, |
| apr_pool_t *pool); |
| |
| /* Store a username in the client. */ |
| svn_error_t *(*store_username) (const char *username, |
| void *auth_baton); |
| |
| } svn_ra_username_authenticator_t; |
| |
| |
| |
| /* A protocol which needs a username and password (used by ra_dav) |
| (matches type svn_ra_auth_simple_password above.) */ |
| typedef struct svn_ra_simple_password_authenticator_t |
| { |
| /* Get a username and password from the client. If FORCE_PROMPT is |
| set, then a prompt will be displayed to the user automatically |
| (rather than looking for cached info from command-line or file.) |
| |
| *USERNAME and *PASSWORD will not only be returned to the RA |
| layer, but libsvn_client will also cache them in the AUTH_BATON. */ |
| svn_error_t *(*get_user_and_pass) (char **username, |
| char **password, |
| void *auth_baton, |
| svn_boolean_t force_prompt, |
| apr_pool_t *pool); |
| |
| /* If any authentication info has been cached in AUTH_BATON (as a |
| result of calling get_user_and_pass), ask the client to store it |
| in the working copy. |
| |
| If this routine is NULL, that means the client is unable (or |
| unwilling) to store auth data. */ |
| svn_error_t *(*store_user_and_pass) (void *auth_baton); |
| |
| } svn_ra_simple_password_authenticator_t; |
| |
| |
| |
| /* A collection of callbacks implemented by libsvn_client which allows |
| an RA layer to "pull" information from the client application, or |
| possibly store information. libsvn_client passes this vtable to |
| RA->open(). |
| |
| Each routine takes a CALLBACK_BATON originally provided with the |
| vtable. */ |
| typedef struct svn_ra_callbacks_t |
| { |
| /* Open a unique temporary file for writing in the working copy. |
| This file will be automatically deleted when FP is closed. */ |
| svn_error_t *(*open_tmp_file) (apr_file_t **fp, |
| void *callback_baton); |
| |
| /* Retrieve an AUTHENTICATOR/AUTH_BATON pair from the client, |
| which represents the protocol METHOD. */ |
| svn_error_t *(*get_authenticator) (void **authenticator, |
| void **auth_baton, |
| enum svn_ra_auth_method method, |
| void *callback_baton, |
| apr_pool_t *pool); |
| |
| /*** The following items may be set to NULL to disallow the RA layer |
| to perform the respective operations of the vtable functions. |
| Perhaps WC props are not defined or are in invalid for this |
| session, or perhaps the commit operation this RA session will |
| perform is a server-side only one that shouldn't do post-commit |
| processing on a working copy path. ***/ |
| |
| /* Fetch working copy properties. |
| ### we might have a problem if the RA layer ever wants a property |
| ### that corresponds to a different revision of the file than |
| ### what is in the WC. we'll cross that bridge one day... */ |
| svn_ra_get_wc_prop_func_t get_wc_prop; |
| |
| /* Set working copy properties. */ |
| svn_ra_set_wc_prop_func_t set_wc_prop; |
| |
| } svn_ra_callbacks_t; |
| |
| |
| |
| /*----------------------------------------------------------------------*/ |
| |
| /* The RA Library */ |
| |
| |
| /* A vtable structure which encapsulates all the functionality of a |
| particular repository-access implementation. |
| |
| Note: libsvn_client will keep an array of these objects, |
| representing all RA libraries that it has simultaneously loaded |
| into memory. Depending on the situation, the client can look |
| through this array and find the appropriate implementation it |
| needs. */ |
| |
| typedef struct svn_ra_plugin_t |
| { |
| /* The proper name of the ra library, (e.g. "ra_dav" or "ra_local") */ |
| const char *name; |
| |
| /* Short doc string printed out by `svn -v` */ |
| const char *description; |
| |
| /* The vtable hooks */ |
| |
| /* Open a repository session to REPOS_URL. Return an opaque object |
| representing this session in *SESSION_BATON, allocated in POOL. |
| |
| CALLBACKS/CALLBACK_BATON is a table of callbacks provided by the |
| client; see svn_ra_callbacks_t above. |
| |
| All RA requests require a session_baton; they will continue to |
| use POOL for memory allocation. */ |
| svn_error_t *(*open) (void **session_baton, |
| svn_stringbuf_t *repos_URL, |
| const svn_ra_callbacks_t *callbacks, |
| void *callback_baton, |
| apr_pool_t *pool); |
| |
| /* Close a repository session. This frees any memory used by the |
| session baton. (To free the session baton itself, simply free |
| the pool it was created in.) */ |
| svn_error_t *(*close) (void *session_baton); |
| |
| /* Get the latest revision number from the repository. This is |
| useful for the `svn status' command. :) */ |
| svn_error_t *(*get_latest_revnum) (void *session_baton, |
| svn_revnum_t *latest_revnum); |
| |
| /* Get the latest revision number at time TIME. */ |
| svn_error_t *(*get_dated_revision) (void *session_baton, |
| svn_revnum_t *revision, |
| apr_time_t tm); |
| |
| /* Set *EDITOR and *EDIT_BATON to an editor for committing changes |
| to the repository, using LOG_MSG as the log message. The |
| revisions being committed against are passed to the editor |
| functions, starting with the rev argument to open_root. The path |
| root of the commit is in the SESSION_BATON's url. |
| |
| These three functions all share CLOSE_BATON: |
| |
| * GET_FUNC is used by the RA layer to fetch any WC properties |
| during the commit. |
| |
| * SET_FUNC is used by the RA layer to set any WC properties, |
| after the commit completes. |
| |
| * CLOSE_FUNC is used by the RA layer to bump the revisions of |
| each committed item, after the commit completes. It may be |
| called multiple times. |
| |
| Any of these functions may be null. |
| |
| After the editor's close_edit function returns successfully, |
| *NEW_REV holds either the new revision, or SVN_INVALID_REVNUM if |
| the commit was a no-op (i.e. nothing was committed); |
| *COMMITTED_DATE holds the repository-side date, or NULL if the |
| date is unavailable; *COMMITTED_AUTHOR holds the repository-side |
| author (i.e., the one recorded as the author of the commit in the |
| repository), or NULL if the author is unavailable. Allocate the |
| latter two in the session. Any of NEW_REV, COMMITTED_DATE, or |
| COMMITTED_AUTHOR may be null, in which case not touched. |
| */ |
| svn_error_t *(*get_commit_editor) (void *session_baton, |
| const svn_delta_editor_t **editor, |
| void **edit_baton, |
| svn_revnum_t *new_rev, |
| const char **committed_date, |
| const char **committed_author, |
| svn_stringbuf_t *log_msg); |
| |
| /* Push the contents of PATH at REVISION into an existing STREAM; |
| PATH is interpreted relative to the url in SESSION_BATON. |
| |
| If REVISION is SVN_INVALID_REVNUM (meaning 'head') and |
| *FETCHED_REV is not NULL, then this function will set |
| *FETCHED_REV to the actual revision that was retrieved. (Some |
| callers want to know, and some don't.) |
| |
| If PROPS is non NULL, it will contain the properties of the file. |
| This means *all* properties: not just ones controlled by the |
| user and stored in the repository fs, but non-tweakable ones |
| generated by the SCM system itself (e.g. 'wcprops', 'entryprops', |
| etc.) |
| |
| ### The parsing of props will be be cleaned up/factorized soon. |
| */ |
| svn_error_t *(*get_file) (void *session_baton, |
| const char *path, |
| svn_revnum_t revision, |
| svn_stream_t *stream, |
| svn_revnum_t *fetched_rev, |
| apr_hash_t **props); |
| |
| |
| /* Check out revision REVISION of the url specified in |
| SESSION_BATON, using EDITOR and EDIT_BATON to create the working |
| copy. If RECURSE is non-zero, create the full working tree, else |
| just its topmost directory. */ |
| svn_error_t *(*do_checkout) (void *session_baton, |
| svn_revnum_t revision, |
| svn_boolean_t recurse, |
| const svn_delta_edit_fns_t *editor, |
| void *edit_baton); |
| |
| |
| /* Ask the network layer to update a working copy. |
| |
| The client initially provides an UPDATE_EDITOR/BATON to the RA |
| layer; this editor contains knowledge of where the change will |
| begin in the working copy (when open_root() is called). |
| |
| In return, the client receives a REPORTER/REPORT_BATON. The |
| client then describes its working-copy revision numbers by making |
| calls into the REPORTER structure; the RA layer assumes that all |
| paths are relative to the URL used to create SESSION_BATON. |
| |
| When finished, the client calls REPORTER->finish_report(). The RA |
| layer then drives UPDATE_EDITOR to update the working copy. |
| UPDATE_TARGET is an optional single path component will restrict |
| the scope of things affected by the update to an entry in the |
| directory represented by the SESSION_BATON's URL, or NULL if the |
| entire directory is meant to be updated. |
| |
| The working copy will be updated to REVISION_TO_UPDATE_TO, or the |
| "latest" revision if this arg is invalid. */ |
| svn_error_t *(*do_update) (void *session_baton, |
| const svn_ra_reporter_t **reporter, |
| void **report_baton, |
| svn_revnum_t revision_to_update_to, |
| svn_stringbuf_t *update_target, |
| svn_boolean_t recurse, |
| const svn_delta_edit_fns_t *update_editor, |
| void *update_baton); |
| |
| /* Ask the network layer to 'switch' a working copy to a new |
| SWITCH_URL; it's another form of do_update(). |
| |
| [Please note: this function cannot be used to switch a single |
| file, only a working copy directory. The main caller of this |
| routine, svn_client_switch, uses get_file and svn_wc_install_file |
| to switch a single file. |
| |
| The client initially provides an UPDATE_EDITOR/BATON to the RA |
| layer; this editor contains knowledge of where the change will |
| begin in the working copy (when open_root() is called). |
| |
| In return, the client receives a REPORTER/REPORT_BATON. The |
| client then describes its working-copy revision numbers by making |
| calls into the REPORTER structure; the RA layer assumes that all |
| paths are relative to the URL used to create SESSION_BATON. |
| |
| When finished, the client calls REPORTER->finish_report(). The RA |
| layer then drives UPDATE_EDITOR to update the working copy. |
| UPDATE_TARGET is an optional single path component will restrict |
| the scope of things affected by the update to an entry in the |
| directory represented by the SESSION_BATON's URL, or NULL if the |
| entire directory is meant to be updated. |
| |
| The working copy will be updated to REVISION_TO_UPDATE_TO, or the |
| "latest" revision if this arg is invalid. */ |
| svn_error_t *(*do_switch) (void *session_baton, |
| const svn_ra_reporter_t **reporter, |
| void **report_baton, |
| svn_revnum_t revision_to_update_to, |
| svn_stringbuf_t *update_target, |
| svn_boolean_t recurse, |
| svn_stringbuf_t *switch_url, |
| const svn_delta_edit_fns_t *update_editor, |
| void *update_baton); |
| |
| /* Ask the network layer to describe the status of a working copy |
| with respect to the HEAD revision of the repository. |
| |
| The client initially provides an STATUS_EDITOR/BATON to the RA |
| layer; this editor contains knowledge of where the change will |
| begin in the working copy (when open_root() is called). |
| |
| In return, the client receives a REPORTER/REPORT_BATON. The |
| client then describes its working-copy revision numbers by making |
| calls into the REPORTER structure; the RA layer assumes that all |
| paths are relative to the URL used to create SESSION_BATON. |
| |
| When finished, the client calls REPORTER->finish_report(). The RA |
| layer then drives STATUS_EDITOR to report, essentially, what |
| would would be modified in the working copy were the client to |
| call do_update(). STATUS_TARGET is an optional single path |
| component will restrict the scope of the status report to an |
| entry in the directory represented by the SESSION_BATON's URL, or |
| NULL if the entire directory is meant to be examined. */ |
| svn_error_t *(*do_status) (void *session_baton, |
| const svn_ra_reporter_t **reporter, |
| void **report_baton, |
| svn_stringbuf_t *status_target, |
| svn_boolean_t recurse, |
| const svn_delta_edit_fns_t *status_editor, |
| void *status_baton); |
| |
| |
| /* Ask the network layer to perform a merge of the differences |
| between START_PATH:START_REVISION and END_PATH:END_REVISION into |
| the working copy. Return a *REPORTER object (and *REPORT_BATON) |
| that the caller can use to describe the working copy target. |
| START_PATH and END_PATH are relative to the *SESSION_BATON's URL. |
| |
| When the callers has finished describing his working copy via the |
| *REPORTER interface, use SETUP_EDITOR/SETUP_EDIT_BATON and |
| FINISH_EDITOR/FINISH_EDIT_BATON to actually perform the merge. |
| |
| MERGE_TARGET, also relative to the *SESSION_BATON's URL, |
| describes the filesystem path associated with the working copy |
| target. */ |
| svn_error_t *(*do_merge) (void *session_baton, |
| const svn_ra_reporter_t **reporter, |
| void **report_baton, |
| const char *start_path, |
| svn_revnum_t start_revision, |
| const char *end_path, |
| svn_revnum_t end_revision, |
| const char *merge_target, |
| const svn_delta_edit_fns_t *setup_editor, |
| void *setup_edit_baton, |
| const svn_delta_edit_fns_t *finish_editor, |
| void *finish_edit_baton); |
| |
| |
| /* Invoke RECEIVER with RECEIVER_BATON on each log message from |
| START to END. START may be greater or less than END; this just |
| controls whether the log messages are processed in descending or |
| ascending revision number order. |
| |
| If START or END is SVN_INVALID_REVNUM, it defaults to youngest. |
| |
| If PATHS is non-null and has one or more elements, then only show |
| revisions in which at least one of 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 svn_stringbuf_t *, |
| relative to the session's common parent. |
| |
| If DISCOVER_CHANGED_PATHS, then each call to receiver passes a |
| `const apr_hash_t *' for the receiver's CHANGED_PATHS argument; |
| the hash's keys are all the paths committed in that revision. |
| Otherwise, each call to receiver passes null for CHANGED_PATHS. |
| |
| If any invocation of RECEIVER returns error, return that error |
| immediately and without wrapping it. |
| |
| See also the documentation for `svn_log_message_receiver_t'. */ |
| 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_log_message_receiver_t receiver, |
| void *receiver_baton); |
| |
| /* Yoshiki Hayashi <yoshiki@xemacs.org> 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 *KIND to node kind associated with PATH at REVISION. If PATH |
| does not exist under REVISION, set *KIND to svn_node_none. PATH |
| is relative to the session's parent URL. */ |
| svn_error_t *(*check_path) (svn_node_kind_t *kind, |
| void *session_baton, |
| const char *path, |
| svn_revnum_t revision); |
| |
| |
| } svn_ra_plugin_t; |
| |
| |
| /* svn_ra_init_func_t : |
| |
| libsvn_client will be reponsible for loading each RA DSO it needs. |
| However, all "ra_FOO" implementations *must* export a function named |
| `svn_ra_FOO_init()' of type `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 (svn_ra_plugin_t *). 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. |
| |
| |
| VSN DATE REASON FOR CHANGE |
| --- ---------- ------------------------------------------------ |
| 1 2001-02-17 Initial revision. |
| */ |
| #define SVN_RA_ABI_VERSION 1 |
| |
| |
| /** Public RA implementations: ADD MORE HERE as necessary. **/ |
| |
| svn_error_t * svn_ra_dav_init (int abi_version, |
| apr_pool_t *pool, |
| apr_hash_t *hash); |
| svn_error_t * svn_ra_local_init (int abi_version, |
| apr_pool_t *pool, |
| apr_hash_t *hash); |
| |
| |
| /*----------------------------------------------------------------------*/ |
| |
| /*** Public Interfaces ***/ |
| |
| /* Every user of the RA layer *must* call this routine and hold on to |
| the RA_BATON returned. This baton contains all known methods of |
| accessing a repository, for use within most svn_client_* routines. */ |
| svn_error_t * svn_ra_init_ra_libs (void **ra_baton, apr_pool_t *pool); |
| |
| |
| /* Return an ra vtable-LIBRARY (already within 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 *DESCRIPTIONS string (allocated in 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 */ |
| |
| |
| /* ---------------------------------------------------------------- |
| * local variables: |
| * eval: (load-file "../../tools/dev/svn-dev.el") |
| * end: |
| */ |
