/* -*- 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_INTERNAL_H_INCLUDED)
#define NET_FOSSIL_SCM_FSL_INTERNAL_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 l,
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 library-level internal APIs which are shared
across the library.
*/
#include "fossil-scm/fossil.h" /* MUST come first b/c of config macros */
#if defined(__cplusplus)
extern "C" {
#endif
typedef struct fsl_acache fsl_acache;
typedef struct fsl_acache_line fsl_acache_line;
typedef struct fsl_id_bag fsl_id_bag;
typedef struct fsl_pq fsl_pq;
typedef struct fsl_pq_e fsl_pq_e;
/** @internal
Queue entry type for the fsl_pq class.
*/
struct fsl_pq_e {
/** RID of the entry. */
fsl_id_t id;
/** Raw data associated with this entry. */
void * p;
/** Priority of this element. */
fsl_double_t value;
};
/** @internal
Empty-initialized fsl_pq_e structure.
*/
#define fsl_pq_e_empty_m {0,NULL,0.0}
/** @internal
A simple priority queue class. Instances _must_ be initialized
by copying fsl_pq_empty or fsl_pq_empty_m (depending on where
the instance lives).
*/
struct fsl_pq {
/** Number of items allocated in this->list. */
fsl_size_t capacity;
/** Number of items used in this->list. */
fsl_size_t used;
/** The queue. It is kept sorted by entry->value. */
fsl_pq_e * list;
};
/** @internal
Empty-initialized fsl_pq struct.
*/
#define fsl_pq_empty_m {0,0,NULL}
/** @internal
Empty-initialized fsl_pq struct.
*/
extern const fsl_pq fsl_pq_empty;
/** @internal
Clears the contents of p, freeing any memory it owns, but not
freeing p. Results are undefined if !p.
*/
void fsl_pq_clear(fsl_pq * p);
/** @internal
Insert element e into the queue. Returns 0 on success,
FSL_RC_OOM on error. Results are undefined if !p or e
is invalid. pData may be NULL.
*/
int fsl_pq_insert(fsl_pq *p, fsl_id_t e,
fsl_double_t v, void *pData);
/** @internal
Extracts (removes) the first element from the queue (the element
with the smallest value) and return its ID. Return 0 if the
queue is empty. If pp is not NULL then *pp is (on success)
assigned to the value member of the extracted element.
*/
fsl_id_t fsl_pq_extract(fsl_pq *p, void **pp);
/** @internal
A container type for lists of db record IDs. This is used in
several places as a cache for record IDs, to keep track of ones
we know about, ones we know that we don't know about, and to
avoid duplicate processing in some contexts.
*/
struct fsl_id_bag {
/**
Number of entries of this->list which are in use (have
a positive value). They need not be contiguous!
*/
fsl_size_t entryCount;
/**
The number of elements allocated for this->list.
*/
fsl_size_t capacity;
/**
The number of elements in this->list which are
"in used". Must be <= capacity.
*/
fsl_size_t used;
/**
Array of IDs this->capacity elements long. "Used" elements
have a positive value. Unused ones are set to 0.
*/
fsl_id_t * list;
};
/** @internal
Initialized-with-defaults fsl_id_bag structure,
intended for copy initialization.
*/
extern const fsl_id_bag fsl_id_bag_empty;
/** @internal
Initialized-with-defaults fsl_id_bag structure,
intended for in-struct initialization.
*/
#define fsl_id_bag_empty_m {\
0/*entryCount*/, 0/*capacity*/, \
0/*used*/, NULL/*list*/ }
/** @internal
Holds one "line" of a fsl_acache cache.
*/
struct fsl_acache_line {
/**
RID of the cached record.
*/
fsl_id_t rid;
/**
Age. Newer is larger.
*/
fsl_int_t age;
/**
Content of the artifact.
*/
fsl_buffer content;
};
/** @internal
Empty-initialized fsl_acache_line structure.
*/
#define fsl_acache_line_empty_m { 0,0,fsl_buffer_empty_m }
/** @internal
A cache for tracking the existence of artifacts while the
internal goings-on of control artifacts are going on.
*/
struct fsl_acache {
/**
Total amount of memory used by cached content.
*/
fsl_int_t szTotal;
/**
Number of entries "used" in this->list.
*/
fsl_size_t used;
/**
Number of slots in this->list.
*/
fsl_size_t capacity;
/**
Next cache counter age. Higher is newer.
*/
fsl_int_t nextAge;
/**
List of cached content, ordered by age.
*/
fsl_acache_line * list;
/**
All artifacts currently in the cache.
*/
fsl_id_bag inCache;
/**
Cache of known-missing content.
*/
fsl_id_bag missing;
/**
Cache of of known-existing content.
*/
fsl_id_bag available;
};
/** @internal
Empty-initialized fsl_acache structure.
*/
#define fsl_acache_empty_m {\
0/*szTotal*/,0/*used*/,0/*capacity*/,\
0/*nextAge*/,NULL/*list*/,\
fsl_id_bag_empty_m/*inCache*/,\
fsl_id_bag_empty_m/*missing*/,\
fsl_id_bag_empty_m/*available*/\
}
/** @internal
Empty-initialized fsl_acache structure.
*/
extern const fsl_acache fsl_acache_empty;
/** @internal
A type for holding a callback/state pair for manifest
crosslinking callbacks.
*/
struct fsl_xlinker {
char const * name;
/** Callback function. */
fsl_deck_xlink_f f;
/** State for this->f's last argument. */
void * state;
};
typedef struct fsl_xlinker fsl_xlinker;
/** Empty-initializes fsl_xlinker struct. */
#define fsl_xlinker_empty_m {NULL,NULL,NULL}
/** Empty-initializes fsl_xlinker struct. */
extern const fsl_xlinker fsl_xlinker_empty;
/** @internal
An array of fsl_xlinker instances.
*/
struct fsl_xlinker_list {
/** Number of used items in this->list. */
fsl_size_t used;
/** Number of slots allocated in this->list. */
fsl_size_t capacity;
/** Array of this->used elements. */
fsl_xlinker * list;
};
typedef struct fsl_xlinker_list fsl_xlinker_list;
/** Empty-initializes fsl_xlinker_list struct. */
#define fsl_xlinker_list_empty_m {0,0,NULL}
/** Empty-initializes fsl_xlinker_list struct. */
extern const fsl_xlinker_list fsl_xlinker_list_empty;
/** @internal
Searches f's crosslink callbacks for an entry with the given
name and returns that entry, or NULL if no match is found. The
returned object is owned by f.
*/
fsl_xlinker * fsl_xlinker_by_name( fsl_cx * f, char const * name );
/* The fsl_cx class is documented in main public header. */
struct fsl_cx {
/**
The main db handle. It is a pointer to the first one of
repo.db, ckout.db, config.db which is opened. Internal code
should rely as little as possible on the actual arrangement of
internal DB handles, and should use fsl_cx_db_repo(),
fsl_cx_db_checkout(), and fsl_cx_db_config() to get a handle
to the specific db they want. Currently they will always
return NULL or the same handle, but that design decision might
change at some point, so the public API treats them as
separate entities.
*/
fsl_db * dbMain;
/**
Marker which tells us whether fsl_cx_finalize() needs
to fsl_free() this instance or not.
*/
void const * allocStamp;
/**
Handle to the currently opened config database.
*/
/**
Holds info directly related to a checkout database.
*/
struct {
/**
Handle to the currently opened checkout database IF the checkout
is the main db.
*/
fsl_db db;
/**
Possibly not needed, but useful for doing absolute-to-relative
path conversions for checking file lists.
The directory part of an opened checkout db. This is currently
only set by fsl_checkout_open_dir().
*/
char * dir;
fsl_id_t rid;
fsl_uuid_str uuid;
} ckout;
/**
Holds info directly related to a repo database.
*/
struct {
/**
Handle to the currently opened repository database IF repo
is the main db.
*/
fsl_db db;
/**
The default user name, for operations which need one.
See fsl_cx_user_set().
*/
char * user;
} repo;
/**
Holds info directly related to a global config database.
*/
struct {
/**
Handle to the currently opened global config database IF config
is the main db.
*/
fsl_db db;
} config;
/**
Output channel used by fsl_output() and friends.
*/
fsl_outputer output;
/**
Can be used to tie client-specific data to the context. Its
finalizer is called when fsl_cx_finalize() cleans up.
*/
fsl_state clientState;
/**
Holds error state. As a general rule, this information is
updated only by routines which need to return more info than a
simple integer error code. This is primarily db-related
routines, where we add the db-driver-provided error state
here. It is not used by "simple" routines for which an integer
code always suffices. APIs which set this should denote it
with a comment like "updates the context's error state on
error."
*/
fsl_error error;
/**
Optimization: reusable scratchpad for
creating/encoding/decoding strings.
*/
fsl_buffer scratch;
/**
A scratchpad specifically for dealing with filename-related,
non-recursive caching.
*/
fsl_buffer fsScratch;
/**
A copy of the config object passed to fsl_cx_init() (or some
default).
*/
fsl_cx_config cxConfig;
/**
Flags, some (or one) of which is runtime-configurable by the
client (see fsl_cx_flag_t). We can get rid of this and add the
flags to the cache member along with the rest of them.
*/
int flags;
/**
List of callbacks for deck crosslinking purposes.
*/
fsl_xlinker_list xlinkers;
/**
A place for caching generic things.
*/
struct {
/**
Cached copy of the allow-symlinks config option, because it
is needed on each stat() call. Negative value=="not yet
determined", 0==no, positive==yes. The negative value means
we need to check the repo config resp. the global config to
see if this is on. We can probably default this to true,
though i don't think(?) fossil(1) does so(?).
*/
char allowSymlinks;
/**
The case-insensitive repo flag.
*/
char caseInsensitive;
/**
Porting artifact. Not yet used.
*/
char ignoreDephantomizations;
/**
Record ID of rcvfrom entry during commits.
*/
fsl_id_t rcvId;
/**
Bool flag: whether or not a running commit process should be
marked as private.
*/
char markPrivate;
/**
Analog to v1's content.c:ignoreDephantomizations flag.
*/
char deferCrosslink;
/**
True if fsl_mf_crosslink_begin() has been called but
fsl_mf_crosslink_end() is still pending.
*/
char isCrosslinking;
/**
Flag indicating that only cluster control artifacts
should be processed by manifest crosslinking.
*/
char xlinkClustersOnly;
/**
Used to tell the content-save internals that a "final
verification" (a.k.a. verify-before-commit) is underway.
*/
char inFinalVerify;
/**
Indicates whether or not this repo has ever seen a manifest.
negative==undetermined, 0==no, positive==yes.
*/
char seenManifest;
/**
TODO: a cache of most recently loaded/freed manifests,
analog to v1's manifest.c:manifestCache array. Won't need
this until we get to a point where we can rebuild or similar
intensive operations.
*/
struct {
/**
Head of the cache list. All insertions/removals happen at
the head.
*/
fsl_deck * head;
/**
TODO: maximum number of entries in the mf linked list.
*/
fsl_uint32_t limit;
/**
Current number of entries in the mf linked list.
*/
fsl_uint32_t size;
} mf;
/**
Artifact cache used during processing of manifests.
*/
fsl_acache arty;
/**
Used during manifest parsing.
*/
fsl_id_bag mfSeen;
/**
Used during the processing of manifests to keep track of
"leaf checks" which need to be done downstream.
*/
fsl_id_bag leafCheck;
/**
Holds the RID of every record awaiting verification
during the verify-at-commit checks.
*/
fsl_id_bag toVerify;
/**
Holds a list of "selected files."
*/
fsl_list selectedFiles;
/**
Infrastructure for fsl_mtime_of_manifest_file(). It
remembers the previous RID so that it knows when it has to
invalidate/rebuild its ancestry cache.
*/
fsl_id_t mtimeManifest;
} cache;
struct {
/**
Holds a list of (fsl_card_J*) records representing custom
ticket table fields available in the db.
Each entry's flags member denote (using fsl_card_J_flags)
whether that field is used by the ticket or ticketchng
tables.
TODO, eventually: add a separate type for these entries. We
use fsl_card_J because the infrastructure is there and they
provide what we need, but fsl_card_J::flags only exists for
this list. A custom type would be smaller than fsl_card_J
(only two members) but adding it requires adding some
infrastructure which isn't worth the effort at the moment.
*/
fsl_list customFields;
/**
Gets set to true (at some point) if the client has the
ticket db table.
*/
char hasTicket;
/**
Gets set to true (at some point) if the client has the
ticket.tkt_ctime db field.
*/
char hasCTime;
/**
Gets set to true (at some point) if the client has the
ticketchnk db table.
*/
char hasChng;
/**
Gets set to true (at some point) if the client has the
ticketchng.rid db field.
*/
char hasChngRid;
} ticket;
/*
Note: no state related to server/user/etc. That is higher-level
stuff. We might need to allow the user to set a default user
name to avoid that he has to explicitly set it on all of the
various Control Artifact-generation bits which need it.
*/
};
/** @internal
Initialized-with-defaults fsl_cx struct.
*/
#define fsl_cx_empty_m { \
NULL /*dbMain*/, \
NULL/*allocStamp*/,\
{/*ckout*/ fsl_db_empty_m /*db*/, NULL /*dir*/, 0/*rid*/, NULL/*uuid*/}, \
{/*repo*/ fsl_db_empty_m /*db*/, NULL/*user*/}, \
{/*config*/ fsl_db_empty_m /*db*/ }, \
fsl_outputer_FILE_m /*output*/, \
fsl_state_empty_m /*clientState*/, \
fsl_error_empty_m /*error*/, \
fsl_buffer_empty_m /*scratch*/, \
fsl_buffer_empty_m /*fsScratch*/, \
fsl_cx_config_empty_m /*cxConfig*/, \
FSL_CX_F_DEFAULTS/*flags*/, \
fsl_xlinker_list_empty_m/*xlinkers*/,\
{/*cache*/ \
-1/*allowSymlinks*/, \
0/*caseInsensitive*/,\
0/*ignoreDephantomizations*/,\
0/*rcvId*/, \
0/*markPrivate*/, \
0/*deferCrosslink*/, \
0/*isCrosslinking*/,\
0/*xlinkClustersOnly*/,\
0/*inFinalVerify*/, \
-1/*seenManifest*/,\
{/*mf*/ NULL/*head*/,5/*max*/,0/*size*/}, \
fsl_acache_empty_m/*arty*/, \
fsl_id_bag_empty_m/*mfSeen*/,\
fsl_id_bag_empty_m/*leafCheck*/,\
fsl_id_bag_empty_m/*toVerify*/, \
fsl_list_empty_m/*selectedFiles*/, \
0/*mtimeManifest*/,\
}, \
{/*ticket*/ \
fsl_list_empty_m/*customFields*/, \
0/*hasTicket*/, \
0/*hasCTime*/, \
0/*hasChng*/, \
0/*hasCngRid*/ \
}\
}
/** @internal
Initialized-with-defaults fsl_cx instance.
*/
extern const fsl_cx fsl_cx_empty;
/*
TODO:
int fsl_buffer_append_getenv( fsl_buffer * b, char const * env )
Fetches the given env var and appends it to b. Returns FSL_RC_NOT_FOUND
if the env var is not set. The primary use for this would be to simplify
the Windows implementation of fsl_find_home_dir().
*/
/** @internal
Searches for a repo.tag entry given name in the given context's
repository db. If found, it returns the record's id. If no
record is found and create is true (non-0) then a tag is created
and its entry id is returned. Returns 0 if it finds no entry, a
negative value on error. On db-level error, f's error state is
updated.
*/
fsl_id_t fsl_tag_id( fsl_cx * f, char const * tag, char create );
/** @internal
Return the number of elements in the bag.
*/
fsl_size_t fsl_id_bag_count(fsl_id_bag *p);
/** @internal
Remove element e from the bag if it exists in the bag. If e is
not in the bag, this is a no-op.
*/
void fsl_id_bag_remove(fsl_id_bag *p, fsl_id_t e);
/** @internal
Return true (non-0) if e in the bag. Return false if it is not.
*/
char fsl_id_bag_contains(fsl_id_bag *p, fsl_id_t e);
/** @internal
Insert element e into the bag if it is not there already.
Returns 0 if it actually inserts something or if it already
contains such an entry, and some other value on error (e.g. FSL_RC_OOM).
*/
int fsl_id_bag_insert(fsl_id_bag *p, fsl_id_t e);
/** @internal
Return the ID of the first element in the bag. Return 0 if the
bag is empty.
*/
fsl_id_t fsl_id_bag_first(fsl_id_bag *p);
/** @internal
Return the next element in the bag after e. Return 0 if
e is the last element in the bag. Any insert or removal from
the bag might reorder the bag.
*/
fsl_id_t fsl_id_bag_next(fsl_id_bag *p, fsl_id_t e);
/** @internal
Frees any memory owned by p, but does not free p.
*/
void fsl_id_bag_clear(fsl_id_bag *p);
/** @internal
Expires the single oldest entry in c. Returns true (non-0) if it
removes an item, else 0.
*/
char fsl_acache_expire_oldest(fsl_acache * c);
/** @internal
Add an entry to the content cache.
This routines transfers the contents of pBlob over to c,
regardless of success or failure. The cache will deallocate
memory when it has finished with it.
Returns 0 on success, FSL_RC_OOM on allocation error. Has undefined
behaviour if !c, rid is not semantically valid, !pBlob (or pBlob
has no content???).
*/
int fsl_acache_insert(fsl_acache * c, fsl_id_t rid, fsl_buffer *pBlob);
/** @internal
Frees all memory held by c, and clears out c's state, but does
not free c. Results are undefined if !c.
*/
void fsl_acache_clear(fsl_acache * c);
/** @internal
Checks f->cache.arty to see if rid is available in the
repository opened by f.
Returns 0 if the content for the given rid is available in the
repo or the cache. Returns FSL_RC_NOT_FOUND if it is not in the
repo nor the cache. Returns some other non-0 code for "real
errors," e.g. FSL_RC_OOM if a cache allocation fails. This
operation may update the cache's contents.
If this function detects a loop in artifact lineage, it fails an
assert() in debug builds and returns FSL_RC_CONSISTENCY in
non-debug builds. That doesn't happen in real life, though.
*/
int fsl_acache_check_available(fsl_cx * f, fsl_id_t rid);
/** @internal
Writes content into the repository database. Returns the record
ID via outRid (if it is not NULL). If the content is already in
the database, it fetches the *outRid but has no side effects
in the repo.
If srcId is >0 then pBlob must contain delta content from
the srcId record. srcId might be a phantom.
pBlob is normally uncompressed text, but if uncompSize>0 then
the pBlob value is assumed to be compressed and uncompSize is
its uncompressed size. If uncompSize>0 then zUuid must be valid.
TODO: we can use fsl_buffer_is_compressed() and friends to
determine this, and remove this parameter.
zUuid is the UUID of the artifact, if it is not NULL. When srcId is
specified then zUuid must always be specified. If srcId is zero,
and zUuid is zero then the correct zUuid is computed from pBlob.
If isPrivate is true, the blob is created as a private record.
If the record already exists but is a phantom, the pBlob content
is inserted and the phatom becomes a real record.
The original content of pBlob is not disturbed. The caller continues
to be responsible for pBlob. This routine does *not* take over
responsibility for freeing pBlob.
If outRid is not NULL the on success *outRid is assigned to the
ID of the underlying blob record.
Returns 0 on success and there are too many potential error cases
to name - this function is a massive beast.
Potential TODO: we don't really need the uncompSize param - we
can deduce it, if needed, based on pBlob's content. We cannot,
however, know the UUID of the decompressed content unless the
client passes it in to us.
@see fsl_content_put()
*/
int fsl_content_put_ex( fsl_cx * f, fsl_buffer const * pBlob,
fsl_uuid_cstr zUuid, fsl_id_t srcId,
fsl_size_t uncompSize, char isPrivate,
fsl_id_t * outRid);
/** @internal
Equivalent to fsl_content_put_ex(f,pBlob,NULL,0,0,0,newRid).
This must only be used for saving raw (non-delta) content.
@see fsl_content_put_ex()
*/
int fsl_content_put( fsl_cx * f, fsl_buffer const * pBlob,
fsl_id_t * newRid);
/** @internal
If the given blob ID refers to deltified repo content, this routine
undeltifies it and replaces its content with its expanded
form.
Returns 0 on success, FSL_RC_MISUSE if !f, FSL_RC_NOT_A_REPO if
f has no opened repository, FSL_RC_RANGE if rid is not positive,
and any number of other potential errors during the db and
content operations. This function treats already unexpanded
content as success.
@see fsl_content_deltify()
*/
int fsl_content_undeltify(fsl_cx * f, fsl_id_t rid);
/** @internal
The converse of fsl_content_undeltify(), this replaces the storage
of the given blob record so that it is a delta of srcid.
If rid is already a delta from some other place then no
conversion occurs and this is a no-op unless force is true.
It never generates a delta that carries a private artifact into
a public artifact. Otherwise, when we go to send the public
artifact on a sync operation, the other end of the sync will
never be able to receive the source of the delta. It is OK to
delta private->private, public->private, and public->public.
Just no private->public delta. For such cases this function
returns 0, as opposed to FSL_RC_ACCESS or some similar code, and
leaves the content untouched.
If srcid is a delta that depends on rid, then srcid is
converted to undelta'd text.
If either rid or srcid contain less than some "small,
unspecified number" of bytes (currently 50), or if the resulting
delta does not achieve a compression of at least 25%, the rid is
left untouched.
Returns 0 if a delta is successfully made or none needs to be
made, non-0 on error.
@see fsl_content_undeltify()
*/
int fsl_content_deltify(fsl_cx * f, fsl_id_t rid,
fsl_id_t srcid, char force);
/** @internal
Creates a new phantom blob with the given UUID and return its
artifact ID via *newId. Returns 0 on success, FSL_RC_MISUSE if
!f or !uuid, FSL_RC_RANGE if fsl_is_uuid(uuid) returns false,
FSL_RC_NOT_A_REPO if f has no repository opened, FSL_RC_ACCESS
if the given uuid has been shunned, and about 20 other potential
error codes from the underlying db calls. If isPrivate is true
_or_ f has been flagged as being in "private mode" then the new
content is flagged as private. newId may be NULL, but if it is
then the caller will have to find the record id himself by using
the UUID (see fsl_uuid_to_rid()).
*/
int fsl_content_new( fsl_cx * f, fsl_uuid_cstr uuid, char isPrivate,
fsl_id_t * newId );
/** @internal
Recompute/rebuild the entire repo.leaf table.
This can be expensive (in time) for a really large repository.
So it is only done for things like a full rebuild.
Returns 0 on success. Error may indicate that f is not a repo.
On error f's error state may be updated.
*/
int fsl_repo_leaves_rebuild(fsl_cx * f);
/** @internal
Check to see if checkin "rid" is a leaf and either add it to the LEAF
table if it is, or remove it if it is not.
Returns 0 on success, FSL_RC_MISUSE if !f or f has no repo db
opened, FSL_RC_RANGE if pid is <=0. Other errors
(e.g. FSL_RC_DB) may indicate that db is not a repo. On error
db's error state may be updated.
*/
int fsl_repo_leaf_check(fsl_cx * f, fsl_id_t pid);
/** @internal
Schedules a leaf check for "rid" and its parents. Returns 0 on
success.
*/
int fsl_repo_leaf_eventually_check( fsl_cx * f, fsl_id_t rid);
/** @internal
Perform all pending leaf checks. Returns 0 on success or if it
has nothing to do.
*/
int fsl_repo_leaf_do_pending_checks(fsl_cx *f);
/** @internal
UNTESTED - the bits which use this are not yet ported.
This initializes some temporary db state for the crosslinking
of tickets.
Returns 0 on success. If it returns 0, the caller must
eventually call fsl_mf_crosslink_end(), otherwise he must not
call fsl_mf_crosslink_end().
This function starts a db transaction if one is not already
active. fsl_mf_crosslink_end() will end it.
*/
int fsl_mf_crosslink_begin(fsl_cx * f);
/** @internal
UNTESTED - the bits which use this are not yet ported.
Must not be called unless fsl_mf_crosslink_begin() has been
called.
Returns 0 on success. On error it initiates (or propagates) a
rollback for the current transaction.
*/
int fsl_mf_crosslink_end(fsl_cx * f);
/** @internal
Inserts a tag into f's repo db. It does not create the related
control artifact - use fsl_tag_add_artifact() for that.
rid is the artifact to which the tag is being applied.
srcId is the artifact that contains the tag. It is often,
but not always, the same as rid.
(TODO: clarify the difference between rid/srcId.)
mtime is the Julian timestamp for the tag. Defaults to
the current time if mtime <= 0.0.
If outRid is not NULL then on success *outRid is assigned
the new record ID of the generated tag.
If a more recent (compared to mtime) entry already exists for
this tag/rid combination then its rid is returned via *outRid
(if outRid is not NULL) and no new entry is created.
Returns 0 on success, and has a huge number of potential error codes.
*/
int fsl_tag_insert( fsl_cx * f,
fsl_tag_type tagtype,
char const * zTag,
char const * zValue,
fsl_id_t srcId,
fsl_double_t mtime,
fsl_id_t rid,
fsl_id_t *outRid );
/** @internal
Propagate all propagatable tags in pid to the children of pid.
*/
int fsl_tag_propagate_all(fsl_cx * f, fsl_id_t pid);
/** @internal
Propagates a tag through the various internal pipelines.
pid is the artifact id to whose children the tag should be
propagated.
tagid is the id of the tag to propagate (the tag.tagid db value).
tagType is the type of tag to propagate. Must be either FSL_TAGTYPE_CANCEL
or FSL_TAGTYPE_PROPAGATING.
origId is the artifact id of the origin tag if tagType ==
FSL_TAGTYPE_PROPAGATING, otherwise it is ignored.
zValue is the optional value for the tag. May be NULL.
mtime is the Julian timestamp for the tag. Must be a valid time
(no defaults here).
This function is unforgiving of invalid values/ranges, and may assert
in debug mode if passed invalid ids (values<=0), a NULL f, or if f has
no opened repo.
*/
int fsl_tag_propagate(fsl_cx *f,
fsl_tag_type tagType,
fsl_id_t pid,
fsl_id_t tagid,
fsl_id_t origId,
const char *zValue,
fsl_double_t mtime );
/** @internal
Remove the PGP signature from a raw artifact, if there is one.
Expects *pz to point to *pn bytes of string memory which might
or might not be prefixed by a PGP signature. If the string is
enveloped in a signature, then upon returning *pz will point to
the first byte after the end of the PGP header and *pn will
contain the length of the content up to, but not including, the
PGP footer.
If *pz does not look like a PGP header then this is a no-op.
Neither pointer may be NULL and *pz must point to *pn bytes of
valid memory.
*/
void fsl_remove_pgp_signature(unsigned char const **pz, fsl_size_t *pn);
/** @internal
Clears the "seen" cache used by manifest parsing. Should be
called by routines which initialize parsing, but not until their
work has finished all parsing (so that recursive parsing can
use it).
*/
void fsl_cx_clear_mf_seen(fsl_cx * f);
/** @internal
Generates an fsl_appendf()-formatted message to stderr and
fatally aborts the application by calling exit(). This is only
(ONLY!) intended for us as a placeholder for certain test cases
and is not thread-safe.
fmt may be empty or NULL, in which case only the code and its
fsl_rc_cstr() representation are output.
This function does not return.
*/
void fsl_fatal( int code, char const * fmt, ... )
#ifdef __GNUC__
__attribute__ ((noreturn))
#endif
;
/** @internal
Translate a filename into a filename-id (fnid). Create a new
fnid if none previously exists. On success returns 0 and sets *rv
to the filename.fnid record value. Returns non-0 on error.
Results are undefined if any parameter is NULL.
*/
int fsl_repo_filename_to_fnid( fsl_cx * f, char const * filename, fsl_id_t * rv );
/** @internal
Clears all fsl_buffer members of db but leaves the rest
intact. If alsoErrorState is true then the error state is also
cleared, else it is kept as well.
*/
void fsl_db_clear_strings(fsl_db * db, char alsoErrorState );
/** @internal
Returns 0 if db appears to have a current repository schema, 1
if it appears to have an out of date schema, and -1 if it
appears to not be a repository. Results are undefined if db is
NULL or not opened.
*/
int fsl_db_repo_verify_schema(fsl_db * db);
/** @internal
Flags for APIs which add phantom blobs to the repository. The
values in this enum derive from fossil(1) code and should not be
changed without careful forethought and (afterwards) testing. A
phantom blob is a blob about whose existence we know but for
which we have no content. This normally happens during sync
or rebuild operations.
*/
enum fsl_phantom_t {
/**
Indicates to fsl_uuid_to_rid2() that no phantom artifact
should be created.
*/
FSL_PHANTOM_NONE = 0,
/**
Indicates to fsl_uuid_to_rid2() that a public phantom
artifact should be created if no artifact is found.
*/
FSL_PHANTOM_PUBLIC = 1,
/**
Indicates to fsl_uuid_to_rid2() that a private phantom
artifact should be created if no artifact is found.
*/
FSL_PHANTOM_PRIVATE = 2
};
typedef enum fsl_phantom_t fsl_phantom_t;
/** @internal
Works like fsl_uuid_to_rid(), with these differences:
- uuid is expected to be a complete UUID, not a prefix.
- If it finds no entry and the mode argument specifies so then
it will add either a public or private phantom entry and return
its new rid. If mode is FSL_PHANTOM_NONE then this this behaves
just like fsl_uuid_to_rid().
Returns a positive value on success, 0 if it finds no entry and
mode==FSL_PHANTOM_NONE, and a negative value on error (e.g. if
fsl_is_uuid(uuid) returns false). Errors which happen after
argument validation will "most likely" update f's error state
with details.
*/
fsl_id_t fsl_uuid_to_rid2( fsl_cx * f, fsl_uuid_cstr uuid,
fsl_phantom_t mode );
/** @internal
Schedules the given rid to be verified at the next commit. This
is used by routines which add artifact records to the blob
table.
The only error case, assuming the arguments are valid, is an
allocation error while appending rid to the internal to-verify
queue.
@see fsl_repo_verify_at_commit()
@see fsl_repo_verify_cancel()
*/
int fsl_repo_verify_before_commit( fsl_cx * f, fsl_id_t rid );
/** @internal
Clears f's verify-at-commit list of RIDs.
@see fsl_repo_verify_at_commit()
@see fsl_repo_verify_before_commit()
*/
void fsl_repo_verify_cancel( fsl_cx * f );
/** @internal
Processes all pending verify-at-commit entries and clears the
to-verify list. Returns 0 on success. On error f's error state
will likely be updated.
ONLY call this from fsl_db_transaction_end() or its delegate (if
refactored).
Verification calls fsl_content_get() to "unpack" content added
in the current transaction. If fetching the content (which
applies any deltas it may need to) fails or a checksum does not
match then this routine fails and returns non-0. Any error f's
error state will be updated.
@see fsl_repo_verify_cancel()
@see fsl_repo_verify_before_commit()
*/
int fsl_repo_verify_at_commit( fsl_cx * f );
/** @internal
Removes all entries from the repo's blob table which are listed
in the shun table. Returns 0 on success. This operation is
wrapped in a transaction. Delta contant which depend on
to-be-shunned content are replaced with their undeltad forms.
Returns 0 on success.
*/
int fsl_repo_shun_artifacts(fsl_cx * f);
/** @internal.
Return a pointer to a string that contains the RHS of an SQL IN
operator which will select config.name values that are part of
the configuration that matches iMatch (a bitmask of
fsl_configset_t values). Ownership of the returned string is
passed to the caller, who must eventually pass it to
fsl_free(). Returns NULL on allocation error.
*/
char *fsl_config_inop_rhs(int iMask);
/** @internal
Return a pointer to a string that contains the RHS of an IN
operator that will select config.name values that are in the
list of control settings. Ownership of the returned string is
passed to the caller, who must eventually pass it to
fsl_free(). Returns NULL on allocation error.
*/
char *fsl_db_setting_inop_rhs();
/**
Hard-coded range of values of the vfile.chnged db field.
*/
enum fsl_vfile_change_t {
FSL_VFILE_CHANGE_NONE = 0,
FSL_VFILE_CHANGE_MOD = 1,
FSL_VFILE_CHANGE_MERGE_MOD = 2,
FSL_VFILE_CHANGE_MERGE_ADD = 3,
FSL_VFILE_CHANGE_INTEGRATE_MOD = 4,
FSL_VFILE_CHANGE_INTEGRATE_ADD = 5
};
/** @internal
Populates f's checkout vfile table with all files from the given
Manifest RID. If vfile already contains entries for that
manifest, it assumes they are loaded and does not insert them
(returning 0 unless cleanup (see below) fails). If manifestRid
is 0 or less then the current checkout's RID is used.
The clearOthers flag is a compatibility flag for fossil(1). The
vfile model allows an arbitrary number of checkin versions to be
installed in it at once, but several of fossil(1)'s reports do
not account for that, and assume only one version is loaded at a
time.
Returns 0 on success, any number of codes on any number of errors.
f must not be NULL and must have opened checkout and repository
databases. In debug builds it will assert that that is so.
*/
int fsl_vfile_load_from_rid(fsl_cx * f, fsl_id_t manifestRid, char clearOthers);
/**
@internal
A bitmask of flags for fsl_vfile_changes_scan().
*/
enum fsl_ckout_sig_t {
/**
The empty flags set.
*/
FSL_VFILE_CKSIG_NONE = 0,
/**
Non-file FS objects throw an error. Not yet implemented.
*/
FSL_VFILE_CKSIG_ENOTFILE = 0x001,
/**
Verify file content using sha1sum, regardless of whether or not
file timestamps differ.
*/
FSL_VFILE_CKSIG_SHA1 = 0x002,
/**
For unchanged or changed-by-merge files, set the mtime to last
check-out time, as determined by fsl_mtime_of_manifest_file().
*/
FSL_VFILE_CKSIG_SETMTIME = 0x004,
/**
Indicates that when populating the vfile table, it should
be cleared of entries for other checkins. This is primarily
for compatibility with fossil(1), which generally assumes
only a single checkin's worth of state is in vfile.
*/
FSL_VFILE_CKSIG_CLEAR_VFILE = 0x008
};
/** @internal
This function populates the vfile table for the given checkin
version ID then compares it against files in the checkout
directory, updating vfile's status for the current checkout
version id as its goes. If vid is 0 or negative then the
current checkout's RID is used in its place. cksigflags
must be a bitmask of fsl_ckout_sig_t values.
Returns 0 on success, non-0 on error.
BUG: this does not properly catch one particular change, where
a file has been replaced by a same-named non-file.
*/
int fsl_vfile_changes_scan(fsl_cx * f, fsl_id_t vid, int cksigFlags);
/** @internal
Creates the ticket and ticketchng tables in f's repository db,
DROPPING them if they already exist. The schema comes from
fsl_cx_schema_ticket().
Returns 0 on success.
*/
int fsl_cx_ticket_create_table(fsl_cx * f);
/** @internal
li is assumed to be empty or contain (fsl_card_J*)
instances. Its contents are freed, along with any memory owned
by li if alsoListMem is true, but li itself is not freed.
Returns 0 on success. Results are undefined if li is NULL.
*/
void fsl_card_J_list_free( fsl_list * li, char alsoListMem );
/** @internal
Values for fsl_card_J::flags.
*/
enum fsl_card_J_flags {
/**
Indicates that the field is used by the ticket table.
*/
FSL_CARD_J_TICKET = 0x01,
/**
Indicates that the field is used by the ticketchng table.
*/
FSL_CARD_J_CHNG = 0x02,
/**
Indicates that the field is used by both the ticket and
ticketchng tables.
*/
FSL_CARD_J_BOTH = FSL_CARD_J_TICKET | FSL_CARD_J_CHNG
};
/** @internal
Loads all custom/customizable ticket fields from f's repo's
ticket table info f. If f has already loaded the list and
forceReload is false, this is a no-op.
Returns 0 on success.
@see fsl_cx::ticket::customFields
*/
int fsl_cx_ticket_load_fields(fsl_cx * f, char forceReload);
/** @internal
A comparison routine for qsort(3) which compares fsl_card_J
instances in a lexical manner based on their names. The order is
important for card ordering in generated manifests.
This routine expects to get passed (fsl_card_J**) (namely from
fsl_list entries), and will not work on an array of J-cards.
*/
int fsl_qsort_cmp_J_cards( void const * lhs, void const * rhs );
/** @internal
The internal version of fsl_deck_parse(). See that function
for details regarding everything but the 3rd argument.
If you happen to know the _correct_ RID for the deck being
parsed, pass it as the rid argument, else pass 0. A negative
value will result in a FSL_RC_RANGE error. This value is (or
will be) only used as an optimization in other places and only
if d->f is not NULL. Passing a positive value has no effect on
how the content is parsed or on the result - it only affects
internal details/optimizations.
*/
int fsl_deck_parse2(fsl_deck * d, fsl_buffer * src, fsl_id_t rid);
/** @internal
This function updates the repo and/or global config databases
with links between the dbs intended for various fossil-level
bookkeeping and housecleaning. These links are not essential to
fossil's functionality but assist in certain "global"
operations.
If no checkout is opened but a repo is, the global config (if
opened) is updated to know about the opened repo db.
If a checkout is opened, global config (if opened) and the
repo are updated to point to the checked-out db.
*/
int fsl_repo_record_filename(fsl_cx * f);
/** @internal
Updates f->ckout.uuid and f->ckout.rid to reflect the current
checkout state. If no checkout is opened, the uuid is
freed/NULLed and the rid is set to 0. Returns 0 on success. If
it returns an error, the f->ckout state is left in a potentially
inconsistent state, and it should not be relied upon
until/unless the error is resolved.
*/
int fsl_cx_update_checkout_uuid( fsl_cx *f );
/** @internal
Not yet implemented - this is a placeholder for a to-be-ported
feature.
*/
int fsl_cx_crosslink_rid( fsl_cx * f, fsl_id_t rid );
#if defined(__cplusplus)
} /*extern "C"*/
#endif
#endif
/* NET_FOSSIL_SCM_FSL_INTERNAL_H_INCLUDED */