/* -*- 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 */