/* -*- Mode: C; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ 
/* vim: set ts=2 et sw=2 tw=80: */
#if !defined(NET_FOSSIL_SCM_FSL_CONFDB_H_INCLUDED)
#define NET_FOSSIL_SCM_FSL_CONFDB_H_INCLUDED
/*
   Copyright (c) 2013 D. Richard Hipp

   This program is free software; you can redistribute it and/or
   modify it under the terms of the Simplified BSD License (also
   known as the "2-Clause License" or "FreeBSD License".)

   This program is distributed in the hope that it will be useful,
   but without any warranty; without even the implied warranty of
   merchantability or fitness for a particular purpose.

   Author contact information:
     drh@hwaci.com
     http://www.hwaci.com/drh/

  ******************************************************************************
   This file declares public APIs for working with fossil-managed content.
*/

#include "fossil-core.h" /* MUST come first b/c of config macros */

#if defined(__cplusplus)
extern "C" {
#endif

  /**
      A flag type for specifying which configuration database a given
      API should be applied to. Used by fsl_config_get_int32() and
      friends.
   */
  enum fsl_confdb_t {
  /**
      Signfies the global-level (per system user) configuration area.
   */
  FSL_CONFDB_GLOBAL = 1,
  /**
      Signfies the repository-level configuration area.
   */
  FSL_CONFDB_REPO = 2,
  /**
      Signfies the checkout-level (a.k.a. "local") configuration area.
   */
  FSL_CONFDB_CKOUT = 3
  };
  typedef enum fsl_confdb_t fsl_confdb_t;

  /**
      Returns the name of the db table associated with the given
      mode. Results are undefined if mode is an invalid value. The
      returned bytes are static and constant.
   */
  char const * fsl_config_table_for_role(fsl_confdb_t mode);

  /**
      Returns a handle to the db associates with the given
      fsl_confdb_t value. Returns NULL if !f or if f has no db for
      that configuration role. Results are undefined if mode is an
      invalid value.
   */
  fsl_db * fsl_config_for_role(fsl_cx * f, fsl_confdb_t mode);

  /**
      Returns the int32 value of a property from one of f's config
      dbs, as specified by the mode parameter. Returns dflt if !f, f
      does not have the requested config db opened, no entry is found,
      or on db-level errors.
   */
  fsl_int32_t fsl_config_get_int32( fsl_cx * f, fsl_confdb_t mode,
                                    fsl_int32_t dflt, char const * key );
  /**
      int64_t counterpart of fsl_config_get_int32().
   */
  fsl_int64_t fsl_config_get_int64( fsl_cx * f, fsl_confdb_t mode,
                                    fsl_int64_t dflt, char const * key );

  /**
      fsl_id_t counterpart of fsl_config_get_int32().
   */
  fsl_id_t fsl_config_get_id( fsl_cx * f, fsl_confdb_t mode,
                              fsl_id_t dflt, char const * key );
  /**
      fsl_double_t counterpart of fsl_config_get_int32().
   */
  fsl_double_t fsl_config_get_double( fsl_cx * f, fsl_confdb_t mode,
                                      fsl_double_t dflt, char const * key );


  /**
      Boolean countertpart of fsl_config_get_int32().
   */
  char fsl_config_get_bool( fsl_cx * f, fsl_confdb_t mode,
                            char dflt, char const * key );

  /**
      String counterpart of fsl_config_get_int32(). The returned memory
      must eventually be freed using fsl_free(). If len is not NULL
      then it is set to the length of the returned string. Returns NULL
      for any sort of error or for a NULL db value.
   */
  char * fsl_config_get_text( fsl_cx * f, fsl_confdb_t mode,
                              char const * key, fsl_size_t * len );

  /**
      fsl_buffer counterpart of fsl_config_get_int32(). Appends the
      value from the config table to b. Returns 0 on success,
      FSL_RC_NOT_FOUND if no row was found or the requested db is not
      opened, FSL_RC_OOM on allocation errror.
   */
  int fsl_config_get_buffer( fsl_cx * f, fsl_confdb_t mode,
                             char const * key, fsl_buffer * b );


  /**
      Sets a configuration variable in one of f's config databases, as
      specified by the mode parameter. Returns 0 on success.  val may
      be NULL. Returns FSL_RC_MISUSE if !f, f does not have that
      database opened, or !key, FSL_RC_RANGE if !key.

      If val is NULL then an SQL NULL is bound instead of an empty
      string.
   */
  int fsl_config_set_text( fsl_cx * f, fsl_confdb_t mode, char const * key, char const * val );

  /**
      The blob counterpart of fsl_config_set_text(). If len is
      negative then fsl_strlen(mem) is used to determine the length of
      the memory.

      If mem is NULL then an SQL NULL is bound instead of an empty
      blob.
   */
  int fsl_config_set_blob( fsl_cx * f, fsl_confdb_t mode, char const * key,
                           void const * mem, fsl_int_t len );
  /**
      int32 counterpart of fsl_config_set_text().
   */
  int fsl_config_set_int32( fsl_cx * f, fsl_confdb_t mode,
                            char const * key, fsl_int32_t val );
  /**
      int64 counterpart of fsl_config_set_text().
   */
  int fsl_config_set_int64( fsl_cx * f, fsl_confdb_t mode,
                            char const * key, fsl_int64_t val );
  /**
      fsl_id_t counterpart of fsl_config_set_text().
   */
  int fsl_config_set_id( fsl_cx * f, fsl_confdb_t mode,
                         char const * key, fsl_id_t val );
  /**
      fsl_double counterpart of fsl_config_set_text().
   */
  int fsl_config_set_double( fsl_cx * f, fsl_confdb_t mode,
                             char const * key, fsl_double_t val );
  /**
      Boolean counterpart of fsl_config_set_text().
   */
  int fsl_config_set_bool( fsl_cx * f, fsl_confdb_t mode,
                           char const * key, char val );

  /**
      "Unsets" (removes) the given key from the given configuration database.
      It is not considered to be an error if the config table does not
      contain that key.
   */
  int fsl_config_unset( fsl_cx * f, fsl_confdb_t mode, char const * key );

  /**
      Begins (or recurses) a transaction on the given configuration
      database.  Returns 0 on success, non-0 on error. On success,
      fsl_config_transaction_end() must eventually be called with the
      same parameters to pop the transaction stack. Returns
      FSL_RC_MISUSE if no db handle is opened for the given
      configuration mode. Assuming all arguments are valid, this
      returns the result of fsl_db_transaction_end() and propagates
      any db-side error into the f object's error state.

      This is primarily intended as an optimization when an app is
      making many changes to a config database. It is not needed when
      the app is only making one or two changes.

      @see fsl_config_transaction_end()
      @see fsl_db_transaction_begin()
   */
  int fsl_config_transaction_begin(fsl_cx * f, fsl_confdb_t mode);

  /**
      Pops the transaction stack pushed by
      fsl_config_transaction_begin(). If rollback is true then the
      transaction is set roll back, otherwise it is allowed to
      continue (if recursive) or committed immediately (if not
      recursive).  Returns 0 on success, non-0 on error. Returns
      FSL_RC_MISUSE if no db handle is opened for the given
      configuration mode. Assuming all arguments are valid, this
      returns the result of fsl_db_transaction_end() and propagates
      any db-side error into the f object's error state.

      @see fsl_config_transaction_begin()
      @see fsl_db_transaction_end()
   */
  int fsl_config_transaction_end(fsl_cx * f, fsl_confdb_t mode, char rollback);

#if defined(__cplusplus)
} /*extern "C"*/
#endif
#endif
/* NET_FOSSIL_SCM_FSL_CONFDB_H_INCLUDED */