svn_client.h

Go to the documentation of this file.

/**
 * @copyright
 * ====================================================================
 *    Licensed to the Apache Software Foundation (ASF) under one
 *    or more contributor license agreements.  See the NOTICE file
 *    distributed with this work for additional information
 *    regarding copyright ownership.  The ASF licenses this file
 *    to you under the Apache License, Version 2.0 (the
 *    "License"); you may not use this file except in compliance
 *    with the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 *    Unless required by applicable law or agreed to in writing,
 *    software distributed under the License is distributed on an
 *    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 *    KIND, either express or implied.  See the License for the
 *    specific language governing permissions and limitations
 *    under the License.
 * ====================================================================
 * @endcopyright
 *
 * @file svn_client.h
 * @brief Subversion's client library
 *
 * Requires:  The working copy library and repository access library.
 * Provides:  Broad wrappers around working copy library functionality.
 * Used By:   Client programs.
 */

#ifndef SVN_CLIENT_H
#define SVN_CLIENT_H

#include <apr.h>
#include <apr_pools.h>
#include <apr_hash.h>
#include <apr_tables.h>
#include <apr_getopt.h>
#include <apr_file_io.h>
#include <apr_time.h>

#include "svn_types.h"
#include "svn_string.h"
#include "svn_wc.h"
#include "svn_opt.h"
#include "svn_ra.h"
#include "svn_diff.h"
#include "svn_auth.h"

#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */



/**
 * Get libsvn_client version information.
 *
 * @since New in 1.1.
 */
const svn_version_t *
svn_client_version(void);

/** Client supporting functions
 *
 * @defgroup clnt_support Client supporting subsystem
 *
 * @{
 */


/*** Authentication stuff ***/

/**  The new authentication system allows the RA layer to "pull"
 *   information as needed from libsvn_client.
 *
 *   @deprecated Replaced by the svn_auth_* functions.
 *   @see auth_fns
 *
 *   @defgroup auth_fns_depr (deprecated) AuthZ client subsystem
 *
 *   @{
 */

/** Create and return @a *provider, an authentication provider of type
 * svn_auth_cred_simple_t that gets information by prompting the user
 * with @a prompt_func and @a prompt_baton.  Allocate @a *provider in
 * @a pool.
 *
 * If both #SVN_AUTH_PARAM_DEFAULT_USERNAME and
 * #SVN_AUTH_PARAM_DEFAULT_PASSWORD are defined as runtime
 * parameters in the @c auth_baton, then @a *provider will return the
 * default arguments when svn_auth_first_credentials() is called.  If
 * svn_auth_first_credentials() fails, then @a *provider will
 * re-prompt @a retry_limit times (via svn_auth_next_credentials()).
 * For infinite retries, set @a retry_limit to value less than 0.
 *
 * @deprecated Provided for backward compatibility with the 1.3 API.
 * Use svn_auth_get_simple_prompt_provider() instead.
 */
SVN_DEPRECATED
void
svn_client_get_simple_prompt_provider(
  svn_auth_provider_object_t **provider,
  svn_auth_simple_prompt_func_t prompt_func,
  void *prompt_baton,
  int retry_limit,
  apr_pool_t *pool);


/** Create and return @a *provider, an authentication provider of type
 * #svn_auth_cred_username_t that gets information by prompting the
 * user with @a prompt_func and @a prompt_baton.  Allocate @a *provider
 * in @a pool.
 *
 * If #SVN_AUTH_PARAM_DEFAULT_USERNAME is defined as a runtime
 * parameter in the @c auth_baton, then @a *provider will return the
 * default argument when svn_auth_first_credentials() is called.  If
 * svn_auth_first_credentials() fails, then @a *provider will
 * re-prompt @a retry_limit times (via svn_auth_next_credentials()).
 * For infinite retries, set @a retry_limit to value less than 0.
 *
 * @deprecated Provided for backward compatibility with the 1.3 API.
 * Use svn_auth_get_username_prompt_provider() instead.
 */
SVN_DEPRECATED
void
svn_client_get_username_prompt_provider(
  svn_auth_provider_object_t **provider,
  svn_auth_username_prompt_func_t prompt_func,
  void *prompt_baton,
  int retry_limit,
  apr_pool_t *pool);


/** Create and return @a *provider, an authentication provider of type
 * #svn_auth_cred_simple_t that gets/sets information from the user's
 * ~/.subversion configuration directory.  Allocate @a *provider in
 * @a pool.
 *
 * If a default username or password is available, @a *provider will
 * honor them as well, and return them when
 * svn_auth_first_credentials() is called.  (see
 * #SVN_AUTH_PARAM_DEFAULT_USERNAME and #SVN_AUTH_PARAM_DEFAULT_PASSWORD).
 *
 * @deprecated Provided for backward compatibility with the 1.3 API.
 * Use svn_auth_get_simple_provider2() instead.
 */
SVN_DEPRECATED
void
svn_client_get_simple_provider(svn_auth_provider_object_t **provider,
                               apr_pool_t *pool);


#if (defined(WIN32) && !defined(__MINGW32__)) || defined(DOXYGEN) || defined(CTYPESGEN) || defined(SWIG)
/**
 * Create and return @a *provider, an authentication provider of type
 * #svn_auth_cred_simple_t that gets/sets information from the user's
 * ~/.subversion configuration directory.  Allocate @a *provider in
 * @a pool.
 *
 * This is like svn_client_get_simple_provider(), except that, when
 * running on Window 2000 or newer (or any other Windows version that
 * includes the CryptoAPI), the provider encrypts the password before
 * storing it to disk. On earlier versions of Windows, the provider
 * does nothing.
 *
 * @since New in 1.2.
 * @note This function is only available on Windows.
 *
 * @note An administrative password reset may invalidate the account's
 * secret key. This function will detect that situation and behave as
 * if the password were not cached at all.
 *
 * @deprecated Provided for backward compatibility with the 1.3 API.
 * Use svn_auth_get_windows_simple_provider() instead.
 */
SVN_DEPRECATED
void
svn_client_get_windows_simple_provider(svn_auth_provider_object_t **provider,
                                       apr_pool_t *pool);
#endif /* WIN32 && !__MINGW32__ || DOXYGEN || CTYPESGEN || SWIG */

/** Create and return @a *provider, an authentication provider of type
 * #svn_auth_cred_username_t that gets/sets information from a user's
 * ~/.subversion configuration directory.  Allocate @a *provider in
 * @a pool.
 *
 * If a default username is available, @a *provider will honor it,
 * and return it when svn_auth_first_credentials() is called.  (see
 * #SVN_AUTH_PARAM_DEFAULT_USERNAME).
 *
 * @deprecated Provided for backward compatibility with the 1.3 API.
 * Use svn_auth_get_username_provider() instead.
 */
SVN_DEPRECATED
void
svn_client_get_username_provider(svn_auth_provider_object_t **provider,
                                 apr_pool_t *pool);


/** Create and return @a *provider, an authentication provider of type
 * #svn_auth_cred_ssl_server_trust_t, allocated in @a pool.
 *
 * @a *provider retrieves its credentials from the configuration
 * mechanism.  The returned credential is used to override SSL
 * security on an error.
 *
 * @deprecated Provided for backward compatibility with the 1.3 API.
 * Use svn_auth_get_ssl_server_trust_file_provider() instead.
 */
SVN_DEPRECATED
void
svn_client_get_ssl_server_trust_file_provider(
  svn_auth_provider_object_t **provider,
  apr_pool_t *pool);


/** Create and return @a *provider, an authentication provider of type
 * #svn_auth_cred_ssl_client_cert_t, allocated in @a pool.
 *
 * @a *provider retrieves its credentials from the configuration
 * mechanism.  The returned credential is used to load the appropriate
 * client certificate for authentication when requested by a server.
 *
 * @deprecated Provided for backward compatibility with the 1.3 API.
 * Use svn_auth_get_ssl_client_cert_file_provider() instead.
 */
SVN_DEPRECATED
void
svn_client_get_ssl_client_cert_file_provider(
  svn_auth_provider_object_t **provider,
  apr_pool_t *pool);


/** Create and return @a *provider, an authentication provider of type
 * #svn_auth_cred_ssl_client_cert_pw_t, allocated in @a pool.
 *
 * @a *provider retrieves its credentials from the configuration
 * mechanism.  The returned credential is used when a loaded client
 * certificate is protected by a passphrase.
 *
 * @deprecated Provided for backward compatibility with the 1.3 API.
 * Use svn_auth_get_ssl_client_cert_pw_file_provider2() instead.
 */
SVN_DEPRECATED
void
svn_client_get_ssl_client_cert_pw_file_provider(
  svn_auth_provider_object_t **provider,
  apr_pool_t *pool);


/** Create and return @a *provider, an authentication provider of type
 * #svn_auth_cred_ssl_server_trust_t, allocated in @a pool.
 *
 * @a *provider retrieves its credentials by using the @a prompt_func
 * and @a prompt_baton.  The returned credential is used to override
 * SSL security on an error.
 *
 * @deprecated Provided for backward compatibility with the 1.3 API.
 * Use svn_auth_get_ssl_server_trust_prompt_provider() instead.
 */
SVN_DEPRECATED
void
svn_client_get_ssl_server_trust_prompt_provider(
  svn_auth_provider_object_t **provider,
  svn_auth_ssl_server_trust_prompt_func_t prompt_func,
  void *prompt_baton,
  apr_pool_t *pool);


/** Create and return @a *provider, an authentication provider of type
 * #svn_auth_cred_ssl_client_cert_t, allocated in @a pool.
 *
 * @a *provider retrieves its credentials by using the @a prompt_func
 * and @a prompt_baton.  The returned credential is used to load the
 * appropriate client certificate for authentication when requested by
 * a server.  The prompt will be retried @a retry_limit times.
 * For infinite retries, set @a retry_limit to value less than 0.
 *
 * @deprecated Provided for backward compatibility with the 1.3 API.
 * Use svn_auth_get_ssl_client_cert_prompt_provider() instead.
 */
SVN_DEPRECATED
void
svn_client_get_ssl_client_cert_prompt_provider(
  svn_auth_provider_object_t **provider,
  svn_auth_ssl_client_cert_prompt_func_t prompt_func,
  void *prompt_baton,
  int retry_limit,
  apr_pool_t *pool);


/** Create and return @a *provider, an authentication provider of type
 * #svn_auth_cred_ssl_client_cert_pw_t, allocated in @a pool.
 *
 * @a *provider retrieves its credentials by using the @a prompt_func
 * and @a prompt_baton.  The returned credential is used when a loaded
 * client certificate is protected by a passphrase.  The prompt will
 * be retried @a retry_limit times. For infinite retries, set @a retry_limit
 * to value less than 0.
 *
 * @deprecated Provided for backward compatibility with the 1.3 API.
 * Use svn_auth_get_ssl_client_cert_pw_prompt_provider() instead.
 */
SVN_DEPRECATED
void
svn_client_get_ssl_client_cert_pw_prompt_provider(
  svn_auth_provider_object_t **provider,
  svn_auth_ssl_client_cert_pw_prompt_func_t prompt_func,
  void *prompt_baton,
  int retry_limit,
  apr_pool_t *pool);

/** @} */

/**
 * Revisions and Peg Revisions
 *
 * @defgroup clnt_revisions Revisions and Peg Revisions
 *
 * A brief word on operative and peg revisions.
 *
 * If the kind of the peg revision is #svn_opt_revision_unspecified, then it
 * defaults to #svn_opt_revision_head for URLs and #svn_opt_revision_working
 * for local paths.
 *
 * For deeper insight, please see the
 * <a href="http://svnbook.red-bean.com/nightly/en/svn.advanced.pegrevs.html">
 * Peg and Operative Revisions</a> section of the Subversion Book.
 */

/**
 * Commit operations
 *
 * @defgroup clnt_commit Client commit subsystem
 *
 * @{
 */

/** This is a structure which stores a filename and a hash of property
 * names and values.
 *
 * @deprecated Provided for backward compatibility with the 1.4 API.
 */
typedef struct svn_client_proplist_item_t
{
  /** The name of the node on which these properties are set. */
  svn_stringbuf_t *node_name;

  /** A hash of (const char *) property names, and (svn_string_t *) property
   * values. */
  apr_hash_t *prop_hash;

} svn_client_proplist_item_t;

/**
 * The callback invoked by svn_client_proplist4().  Each invocation
 * provides the regular and/or inherited properties of @a path, which is
 * either a working copy path or a URL.  If @a prop_hash is not @c NULL, then
 * it maps explicit <tt>const char *</tt> property names to
 * <tt>svn_string_t *</tt> explicit property values.  If @a inherited_props
 * is not @c NULL, then it is a depth-first ordered array of
 * #svn_prop_inherited_item_t * structures representing the
 * properties inherited by @a path.  Use @a scratch_pool for all temporary
 * allocations.
 *
 * The #svn_prop_inherited_item_t->path_or_url members of the
 * #svn_prop_inherited_item_t * structures in @a inherited_props are
 * URLs if @a path is a URL or if @a path is a working copy path but the
 * property represented by the structure is above the working copy root (i.e.
 * the inherited property is from the cache).  In all other cases the
 * #svn_prop_inherited_item_t->path_or_url members are absolute working copy
 * paths.
 *
 * @since New in 1.8.
 */
typedef svn_error_t *(*svn_proplist_receiver2_t)(
  void *baton,
  const char *path,
  apr_hash_t *prop_hash,
  apr_array_header_t *inherited_props,
  apr_pool_t *scratch_pool);

/**
 * Similar to #svn_proplist_receiver2_t, but doesn't return inherited
 * properties.
 *
 * @deprecated Provided for backward compatibility with the 1.7 API.
 *
 * @since New in 1.5.
 */
typedef svn_error_t *(*svn_proplist_receiver_t)(
  void *baton,
  const char *path,