view release on metacpan or  search on metacpan

src/subversion/subversion/include/svn_config.h  view on Meta::CPAN


/** Accessing cached authentication data in the user config area.
 *
 * @defgroup cached_authentication_data Cached authentication data
 * @{
 */


/** A hash-key pointing to a realmstring.  Every file containing
 * authentication data should have this key.
 */
#define SVN_CONFIG_REALMSTRING_KEY  "svn:realmstring"

/** Use @a cred_kind and @a realmstring to locate a file within the
 * ~/.subversion/auth/ area.  If the file exists, initialize @a *hash
 * and load the file contents into the hash, using @a pool.  If the
 * file doesn't exist, set @a *hash to NULL.
 *
 * If @a config_dir is not NULL it specifies a directory from which to
 * read the config overriding all other sources.
 *
 * Besides containing the original credential fields, the hash will
 * also contain @c SVN_CONFIG_REALMSTRING_KEY.  The caller can examine
 * this value as a sanity-check that the correct file was loaded.
 *
 * The hashtable will contain <tt>const char *</tt> keys and
 * <tt>svn_string_t *</tt> values.
 */
svn_error_t *
svn_config_read_auth_data(apr_hash_t **hash,
                          const char *cred_kind,
                          const char *realmstring,
                          const char *config_dir,
                          apr_pool_t *pool);

/** Use @a cred_kind and @a realmstring to create or overwrite a file
 * within the ~/.subversion/auth/ area.  Write the contents of @a hash into
 * the file.  If @a config_dir is not NULL it specifies a directory to read
 * the config overriding all other sources.
 *
 * Also, add @a realmstring to the file, with key @c
 * SVN_CONFIG_REALMSTRING_KEY.  This allows programs (or users) to
 * verify exactly which set credentials live within the file.
 *
 * The hashtable must contain <tt>const char *</tt> keys and
 * <tt>svn_string_t *</tt> values.
 */
svn_error_t *
svn_config_write_auth_data(apr_hash_t *hash,
                           const char *cred_kind,
                           const char *realmstring,
                           const char *config_dir,
                           apr_pool_t *pool);


/** Callback for svn_config_walk_auth_data().
 *
 * Called for each credential walked by that function (and able to be
 * fully purged) to allow perusal and selective removal of credentials.
 *
 * @a cred_kind and @a realmstring specify the key of the credential.
 * @a hash contains the hash data associated with the record.
 *
 * Before returning set @a *delete_cred to TRUE to remove the credential from
 * the cache; leave @a *delete_cred unchanged or set it to FALSE to keep the
 * credential.
 *
 * Implementations may return #SVN_ERR_CEASE_INVOCATION to indicate
 * that the callback should not be called again.  Note that when that
 * error is returned, the value of @a delete_cred will still be
 * honored and action taken if necessary.  (For other returned errors,
 * @a delete_cred is ignored by svn_config_walk_auth_data().)
 *
 * @since New in 1.8.
 */
typedef svn_error_t *
(*svn_config_auth_walk_func_t)(svn_boolean_t *delete_cred,
                               void *cleanup_baton,
                               const char *cred_kind,
                               const char *realmstring,
                               apr_hash_t *hash,
                               apr_pool_t *scratch_pool);

/** Call @a walk_func with @a walk_baton and information describing
 * each credential cached within the Subversion auth store located
 * under @a config_dir.  If the callback sets its delete_cred return
 * flag, delete the associated credential.
 *
 * If @a config_dir is not NULL, it must point to an alternative
 * config directory location. If it is NULL, the default location
 * is used.
 *
 * @note @a config_dir may only be NULL in 1.8.2 and later.
 *
 * @note Removing credentials from the config-based disk store will
 * not purge them from any open svn_auth_baton_t instance.  Consider
 * using svn_auth_forget_credentials() -- from the @a cleanup_func,
 * even -- for this purpose.
 *
 * @note Removing credentials from the config-based disk store will
 * not also remove any related credentials from third-party password
 * stores.  (Implementations of @a walk_func which delete credentials
 * may wish to consult the "passtype" element of @a hash, if any, to
 * see if a third-party store -- such as "gnome-keyring" or "kwallet"
 * is being used to hold the most sensitive portion of the credentials
 * for this @a cred_kind and @a realmstring.)
 *
 * @see svn_auth_forget_credentials()
 *
 * @since New in 1.8.
 */
svn_error_t *
svn_config_walk_auth_data(const char *config_dir,
                          svn_config_auth_walk_func_t walk_func,
                          void *walk_baton,
                          apr_pool_t *scratch_pool);

/** Put the absolute path to the user's configuration directory,
 * or to a file within that directory, into @a *path.