libfossil
repo.h
Go to the documentation of this file.
1/* -*- Mode: C; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2/* vim: set ts=2 et sw=2 tw=80: */
3#if !defined(ORG_FOSSIL_SCM_FSL_REPO_H_INCLUDED)
4#define ORG_FOSSIL_SCM_FSL_REPO_H_INCLUDED
5/*
6 Copyright 2013-2021 The Libfossil Authors, see LICENSES/BSD-2-Clause.txt
7
8 SPDX-License-Identifier: BSD-2-Clause-FreeBSD
9 SPDX-FileCopyrightText: 2021 The Libfossil Authors
10 SPDX-FileType: Code
11
12 Heavily indebted to the Fossil SCM project (https://fossil-scm.org).
13*/
14
15/** @file repo.h
16
17 repo.h declares APIs specifically dealing with repository-db-side
18 state, as opposed to specifically checkout-side state or
19 non-content-related APIs.
20*/
21
22#include "db.h" /* MUST come first b/c of config macros */
23#include "hash.h"
24
25#if defined(__cplusplus)
26extern "C" {
27#endif
28
29typedef struct fsl_card_F fsl_card_F;
30typedef struct fsl_card_J fsl_card_J;
31typedef struct fsl_card_Q fsl_card_Q;
32typedef struct fsl_card_T fsl_card_T;
34typedef struct fsl_deck fsl_deck;
35typedef struct fsl_uperm fsl_uperm;
36
37/**
38 Opens the given db file name as f's repository. Returns 0 on
39 success. On error it sets f's error state and returns that code
40 unless the error was FSL_RC_MISUSE (which indicates invalid
41 arguments and it does not set the error state).
42
43 Returns FSL_RC_ACCESS if f already has an opened repo db (use
44 fsl_repo_close() or fsl_ckout_close() to close it).
45
46 Returns FSL_RC_NOT_FOUND if repoDbFile is not found, as this
47 routine cannot create a new repository db.
48
49 Results are undefined if any argument is NULL.
50
51 When a repository is opened, the fossil-level user name
52 associated with f (if any) is overwritten with the default user
53 from the repo's login table (the one with uid=1). Thus
54 fsl_cx_user_get() may return a value even if the client has not
55 called fsl_cx_user_set().
56
57 It would be nice to have a parameter specifying that the repo
58 should be opened read-only. That's not as straightforward as it
59 sounds because of how the various dbs are internally managed
60 (via one db handle). Until then, the permissions of the
61 underlying repo file will determine how it is opened. i.e. a
62 read-only repo will be opened read-only.
63
64
65 Potentially interesting side-effects:
66
67 - On success this re-sets several bits of f's configuration to
68 match the repository-side settings.
69
70 @see fsl_repo_create()
71 @see fsl_repo_close()
72 @see fsl_close_scm_dbs()
73*/
74FSL_EXPORT int fsl_repo_open( fsl_cx * f, char const * repoDbFile/*, char readOnlyCurrentlyIgnored*/ );
75
76/**
77 This function is a programmatic interpretation of
78 this table:
79
80 https://fossil-scm.org/index.html/doc/trunk/www/fileformat.wiki#summary
81
82 For a given control artifact type and a card name in the form of
83 the card name's letter (e.g. 'A', 'W', ...), this function
84 returns 0 (false) if that card type is not permitted in this
85 control artifact type, a negative value if the card is optional
86 for this artifact type, and a positive value if the card type is
87 required for this artifact type.
88
89 As a special case, if t==FSL_SATYPE_ANY then this function
90 always returns a negative value as long as card is a valid card
91 letter.
92
93 Another special case: when t==FSL_SATYPE_CHECKIN and card=='F',
94 this returns a negative value because the table linked to above
95 says F-cards are optional. In practice we have yet to find a use
96 for checkins with no F-cards, so this library currently requires
97 F-cards at checkin-time even though this function reports that
98 they are optional.
99*/
101
102/**
103 Artifact tag types used by the Fossil framework. Their values
104 are a hard-coded part of the Fossil format, and not subject to
105 change (only extension, possibly).
106*/
108/**
109 Sentinel value for use with constructors/initializers.
110*/
112/**
113 The "cancel tag" indicator, a.k.a. an anti-tag.
114*/
116/**
117 The "add tag" indicator, a.k.a. a singleton tag.
118*/
120/**
121 The "propagating tag" indicator.
122*/
124};
126
127/**
128 Hard-coded IDs used by the 'tag' table of repository DBs. These
129 values get installed as part of the base Fossil db schema in new
130 repos, and they must never change.
131*/
133/**
134 DB string tagname='bgcolor'.
135*/
137/**
138 DB: tag.tagname='comment'.
139*/
141/**
142 DB: tag.tagname='user'.
143*/
145/**
146 DB: tag.tagname='date'.
147*/
149/**
150 DB: tag.tagname='hidden'.
151*/
153/**
154 DB: tag.tagname='private'.
155*/
157/**
158 DB: tag.tagname='cluster'.
159*/
161/**
162 DB: tag.tagname='branch'.
163*/
165/**
166 DB: tag.tagname='closed'.
167*/
169/**
170 DB: tag.tagname='parent'.
171*/
173/**
174 DB: tag.tagname='note'
175
176 Extra text appended to a check-in comment.
177*/
179
180/**
181 Largest tag ID reserved for internal use.
182*/
184};
185
186
187/**
188 Returns one of '-', '+', or '*' for a valid input parameter, 0
189 for any other value.
190*/
192
193
194/**
195 A list of fsl_card_F objects. F-cards used a custom list type,
196 instead of the framework's generic fsl_list, because experience has
197 shown that the number of (de)allocations we need for F-card lists
198 has a large negative impact when parsing and creating artifacts en
199 masse. This list type, unlike fsl_list, uses a conventional object
200 array approach to storage, as opposed to an array of pointers (each
201 entry of which has to be separately allocated).
202
203 These lists, and F-cards in generally, are typically maintained
204 internally in the library. There's probably "no good reason" for
205 clients to manipulate them.
206*/
208 /**
209 The list of F-cards. The first this->used elements are in-use.
210 This pointer may change any time the list is reallocated.
211 */
213 /**
214 The number of entries in this->list which are in use.
215 */
216 uint32_t used;
217 /**
218 The number of entries currently allocated in this->list.
219 */
220 uint32_t capacity;
221 /**
222 An internal cursor into this->list, used primarily for
223 properly traversing the file list in delta manifests.
224
225 Maintenance notes: internal updates to this member are the only
226 reason some of the deck APIs require a non-const deck. This type
227 needs to be signed for compatibility with some of the older
228 algos, e.g. fsl__deck_F_seek_base().
229 */
230 int32_t cursor;
231 /**
232 Internal flags. Never, ever modify these from client code.
233 */
234 uint32_t flags;
235};
237/** Empty-initialized fsl_card_F instance for const copy
238 initialization */
239#define fsl_card_F_list_empty_m {NULL, 0, 0, 0, 0}
240/** Empty-initialized fsl_card_F instance for non-const copy
241 initialization */
243
244/**
245 A "deck" stores (predictably enough) a collection of "cards."
246 Cards are constructs embedded within Fossil's Structural Artifacts
247 to denote various sorts of changes in a Fossil repository, and a
248 Deck encapsulates the cards for a single Structural Artifact of an
249 arbitrary type, e.g. Manifest (a.k.a. "checkin") or Cluster. A card
250 is basically a command with a single-letter name and a well-defined
251 signature for its arguments. Each card is represented by a member
252 of this struct whose name is the same as the card type
253 (e.g. fsl_card::C holds a C-card and fsl_card::F holds a list of
254 F-card). Each type of artifact only allows certain types of
255 card. The complete list of valid card/construct combinations can be
256 found here:
257
258 https://fossil-scm.org/home/doc/trunk/www/fileformat.wiki#summary
259
260 fsl_card_is_legal() can be used determine if a given card type
261 is legal (per the above chart) with a given Control Artifiact
262 type (as stored in the fsl_deck::type member).
263
264 The type member is used by some algorithms to determine which
265 operations are legal on a given artifact type, so that they can
266 fail long before the user gets a chance to add a malformed artifact
267 to the database. Clients who bypass the fsl_deck APIs and
268 manipulate the deck's members "by hand" (so to say) effectively
269 invoke undefined behaviour.
270
271 The various routines to add/set cards in the deck are named
272 fsl_deck_CARDNAME_add() resp. fsl_deck_CARDNAME_set(). The "add"
273 functions represent cards which may appear multiple times
274 (e.g. the 'F' card) or have multiple values (the 'P' card), and
275 those named "set" represent unique or optional cards. The R-card
276 is the outlier, with fsl_deck_R_calc(). NEVER EVER EVER directly
277 modify a member of this struct - always use the APIs. The
278 library performs some optimizations which can lead to corrupt
279 memory and invalid free()s if certain members' values are
280 directly replaced by the client (as opposed to via the APIs).
281
282 Note that the 'Z' card is not in this structure because it is a
283 hash of the other inputs and is calculated incrementally and
284 appended automatically by fsl_deck_output().
285
286 All non-const pointer members of this structure are owned by the
287 structure instance unless noted otherwise (the fsl_deck::f member
288 being the notable exception).
289
290 Maintenance reminder: please keep the card members alpha sorted to
291 simplify eyeball-searching through their docs.
292
293 @see fsl_deck_malloc()
294 @see fsl_deck_init()
295 @see fsl_deck_parse()
296 @see fsl_deck_load_rid()
297 @see fsl_deck_finalize()
298 @see fsl_deck_clean()
299 @see fsl_deck_save()
300 @see fsl_deck_A_set()
301 @see fsl_deck_B_set()
302 @see fsl_deck_C_set()
303 @see fsl_deck_D_set()
304 @see fsl_deck_E_set()
305 @see fsl_deck_F_add()
306 @see fsl_deck_J_add()
307 @see fsl_deck_K_set()
308 @see fsl_deck_L_set()
309 @see fsl_deck_M_add()
310 @see fsl_deck_N_set()
311 @see fsl_deck_P_add()
312 @see fsl_deck_Q_add()
313 @see fsl_deck_R_set()
314 @see fsl_deck_T_add()
315 @see fsl_deck_branch_set()
316 @see fsl_deck_U_set()
317 @see fsl_deck_W_set()
318*/
319struct fsl_deck {
320 /**
321 Specifies the the type (or eventual type) of this
322 artifact. The function fsl_card_is_legal() can be used to
323 determined if a given card type is legal for a given value of
324 this member. APIs which add/set cards use that to determine if
325 the operation requested by the client is semantically legal.
326 */
328
329 /**
330 DB repo.blob.rid value. Normally set by fsl_deck_load_rid().
331 */
333
334 /**
335 The Fossil context responsible for this deck. Though this data
336 type is normally, at least conceptually, free of any given fossil
337 context, many related algorithms need a context in order to
338 perform db- or caching-related work, as well as to simplify error
339 message propagation. We store this as a struct member to keep all
340 such algorithms from redundantly requiring both pieces of
341 information as arguments.
342
343 This object does not own the context and the context object must
344 outlive this deck instance.
345 */
347
348 /**
349 The 'A' (attachment) card. Only used by FSL_SATYPE_ATTACHMENT
350 decks. The spec currently specifies only 1 A-card per
351 manifest, but conceptually this could/should be a list.
352 */
353 struct {
354 /**
355 Filename of the A-card.
356 */
357 char * name;
358
359 /**
360 Name of wiki page, or UUID of ticket or event (technote), to
361 which the attachment applies.
362 */
363 char * tgt;
364
365 /**
366 UUID of the file being attached via the A-card.
367 */
369 } A;
370
371 struct {
372 /**
373 The 'B' (baseline) card holds the UUID of baseline manifest.
374 This is empty for baseline manifests and holds the UUID of
375 the parent for delta manifests.
376 */
378
379 /**
380 Baseline manifest corresponding to this->B. It is loaded on
381 demand by routines which need it, typically by calling
382 fsl_deck_F_rewind() (unintuitively enough!). The parent/child
383 relationship in Fossil is the reverse of conventional -
384 children own their parents, not the other way
385 around. i.e. this->baseline will get cleaned up when the child
386 part of that relationship is cleaned up.
387 */
389 } B;
390 /**
391 The 'C' (comment) card.
392 */
393 char * C;
394
395 /**
396 The 'D' (date) card, in Julian format.
397 */
398 double D;
399
400 /**
401 The 'E' (event) card.
402 */
403 struct {
404 /**
405 The 'E' card's date in Julian Day format.
406 */
407 double julian;
408
409 /**
410 The 'E' card's UUID.
411 */
413 } E;
414
415 /**
416 The 'F' (file) card container.
417 */
419
420 /**
421 UUID for the 'G' (forum thread-root) card.
422 */
424
425 /**
426 The H (forum title) card.
427 */
428 char * H;
429
430 /**
431 UUID for the 'I' (forum in-response-to) card.
432 */
434
435 /**
436 The 'J' card specifies changes to "value" of "fields" in
437 tickets (FSL_SATYPE_TICKET).
438
439 Holds (fsl_card_J*) entries.
440 */
442
443 /**
444 UUID for the 'K' (ticket) card.
445 */
447
448 /**
449 The 'L' (wiki name/title) card.
450 */
451 char * L;
452
453 /**
454 List of UUIDs (fsl_uuid_str) in a cluster ('M' cards).
455 */
457
458 /**
459 The 'N' (comment mime type) card. Note that this is only
460 ostensibly supported by fossil, but fossil does not (as of
461 2021-04-13) honor this value and always assumes that its value is
462 "text/x-fossil-wiki".
463 */
464 char * N;
465
466 /**
467 List of UUIDs of parents ('P' cards). Entries are of type
468 (fsl_uuid_str).
469 */
471
472 /**
473 'Q' (cherry pick) cards. Holds (fsl_card_Q*) entries.
474 */
476
477 /**
478 The R-card holds an MD5 hash which is calculated based on the
479 names, sizes, and contents of the files included in a
480 manifest. See the class-level docs for a link to a page which
481 describes how this is calculated.
482 */
483 char * R;
484
485 /**
486 List of 'T' (tag) cards. Holds (fsl_card_T*) instances.
487 */
489
490 /**
491 The U (user) card.
492 */
493 char * U;
494
495 /**
496 The W (wiki content) card.
497 */
499
500 /**
501 This is part of an optimization used when parsing fsl_deck
502 instances from source text. For most types of card we re-use
503 string values in the raw source text rather than duplicate them,
504 and that requires storing the original text (as passed to
505 fsl_deck_parse()). This requires that clients never tinker
506 directly with values in a fsl_deck, in particular never assign
507 over them or assume they know who allocated the memory for that
508 bit.
509 */
511
512 /**
513 To potentially be used for a manifest cache.
514 */
516
517 /**
518 A marker which tells fsl_deck_finalize() whether or not
519 fsl_deck_malloc() allocated this instance (in which case
520 fsl_deck_finalize() will fsl_free() it) or not (in which case
521 it does not fsl_free() it).
522 */
523 void const * allocStamp;
524};
525
526/**
527 Initialized-with-defaults fsl_deck structure, intended for copy
528 initialization.
529*/
531
532/**
533 Initialized-with-defaults fsl_deck structure, intended for
534 in-struct and const copy initialization.
535*/
536#define fsl_deck_empty_m { \
537 FSL_SATYPE_ANY /*type*/, \
538 0/*rid*/, \
539 NULL/*f*/, \
540 {/*A*/ NULL /* name */, \
541 NULL /* tgt */, \
542 NULL /* src */}, \
543 {/*B*/ NULL /*uuid*/, \
544 NULL /*baseline*/}, \
545 NULL /* C */, \
546 0.0 /*D*/, \
547 {/*E*/ 0.0 /* julian */, \
548 NULL /* uuid */}, \
549 /*F*/ fsl_card_F_list_empty_m, \
550 0/*G*/,0/*H*/,0/*I*/, \
551 fsl_list_empty_m /* J */, \
552 NULL /* K */, \
553 NULL /* L */, \
554 fsl_list_empty_m /* M */, \
555 NULL /* N */, \
556 fsl_list_empty_m /* P */, \
557 fsl_list_empty_m /* Q */, \
558 NULL /* R */, \
559 fsl_list_empty_m /* T */, \
560 NULL /* U */, \
561 fsl_buffer_empty_m /* W */, \
562 fsl_buffer_empty_m/*content*/, \
563 NULL/*next*/, \
564 NULL/*allocStamp*/ \
565 }
566
567
568/**
569 Allocates a new fsl_deck instance. Returns NULL on allocation
570 error. The returned value must eventually be passed to
571 fsl_deck_finalize() to free its resources.
572
573 @see fsl_deck_finalize()
574 @see fsl_deck_clean()
575*/
577
578/**
579 Frees all resources belonging to the given deck's members
580 (including its parents, recursively), and wipes deck clean of most
581 state, but does not free() deck. Is a no-op if deck is NULL. As a
582 special case, the (allocStamp, f) members of deck are kept intact.
583
584 @see fsl_deck_finalize()
585 @see fsl_deck_malloc()
586 @see fsl_deck_clean2()
587*/
589
590/**
591 A variant of fsl_deck_clean() which "returns" its content buffer
592 for re-use by transferring, after ensuring proper cleanup of its
593 internals, its own content buffer's bytes into the given target
594 buffer. Note that decks created "manually" do not have any content
595 buffer contents, but those loaded via fsl_deck_load_rid() do. This
596 function will fsl_buffer_swap() the contents of the given buffer
597 (if any) with its own buffer, clean up its newly-acquired memory
598 (tgt's previous contents, if any), and fsl_buffer_reuse() the
599 output buffer.
600
601 If tgt is NULL, this behaves exactly like fsl_deck_clean().
602*/
604
605/**
606 Frees all memory owned by deck (see fsl_deck_clean()). If deck
607 was allocated using fsl_deck_malloc() then this function
608 fsl_free()'s it, otherwise it does not free it.
609
610 @see fsl_deck_malloc()
611 @see fsl_deck_clean()
612*/
614
615/**
616 Sets the A-card for an Attachment (FSL_SATYPE_ATTACHMENT)
617 deck. Returns 0 on success.
618
619 Returns FSL_RC_MISUSE if any of (mf, filename, target) are NULL,
620 FSL_RC_RANGE if !*filename or if uuidSrc is not NULL and
621 fsl_is_uuid(uuidSrc) returns false.
622
623 Returns FSL_RC_TYPE if mf is not (as determined by its mf->type
624 member) of a deck type capable of holding 'A' cards. (Only decks
625 of type FSL_SATYPE_ATTACHMENT may hold an 'A' card.) If uuidSrc
626 is NULL or starts with a NUL byte then it is ignored, otherwise
627 the same restrictions apply to it as to target.
628
629 The target parameter represents the "name" of the
630 wiki/ticket/event record to which the attachment applies. For
631 wiki pages this is their normal name (e.g. "MyWikiPage"). For
632 events and tickets it is their full 40-byte UUID.
633
634 uuidSrc is the UUID of the attachment blob itself. If it is NULL
635 or empty then this card indicates that the attachment will be
636 "deleted" (insofar as anything is ever deleted in Fossil).
637*/
638FSL_EXPORT int fsl_deck_A_set( fsl_deck * mf, char const * filename,
639 char const * target,
640 fsl_uuid_cstr uuidSrc);
641
642/**
643 Sets or unsets (if uuidBaseline is NULL or empty) the B-card for
644 the given manifest to a copy of the given UUID. Returns 0 on
645 success, FSL_RC_MISUSE if !mf, FSL_RC_OOM on allocation
646 error. Setting this will free any prior values in mf->B, including
647 a previously loaded mf->B.baseline.
648
649 If uuidBaseline is not NULL and fsl_is_uuid() returns false,
650 FSL_RC_SYNTAX is returned. If it is NULL the current value is
651 freed (semantically, though the deck may still own the memory), the
652 B card is effectively removed, and 0 is returned.
653
654 Returns FSL_RC_TYPE if mf is not syntactically allowed to have
655 this card card (as determined by
656 fsl_card_is_legal(mf->type,...)).
657
658 Sidebar: the ability to unset this card is unusual within this API,
659 and is a requirement the library-internal delta manifest creation
660 process. Most of the card-setting APIs, even when they are
661 described as working like this one, do not accept NULL hash values.
662*/
664
665/**
666 Semantically identical to fsl_deck_B_set() but sets the C-card and
667 does not place a practical limit on the comment's length. comment
668 must be the comment text for the change being applied. If the
669 given length is negative, fsl_strlen() is used to determine its
670 length.
671*/
672FSL_EXPORT int fsl_deck_C_set( fsl_deck * mf, char const * comment, fsl_int_t cardLen);
673
674/**
675 Sets mf's D-card as a Julian Date value. Returns FSL_RC_MISUSE if
676 !mf, FSL_RC_RANGE if date is negative, FSL_RC_TYPE if a D-card is
677 not valid for the given deck, else 0. Passing a value of 0
678 effectively unsets the card.
679*/
680FSL_EXPORT int fsl_deck_D_set( fsl_deck * mf, double date);
681
682/**
683 Sets the E-card in the given deck. date may not be negative -
684 use fsl_db_julian_now() or fsl_julian_now() to get a default
685 time if needed. Retursn FSL_RC_MISUSE if !mf or !uuid,
686 FSL_RC_RANGE if date is not positive, FSL_RC_RANGE if uuid is
687 not a valid UUID string.
688
689 Note that the UUID for an event, unlike most other UUIDs, need
690 not be calculated - it may be a random hex string, but it must
691 pass the fsl_is_uuid() test. Use fsl_db_random_hex() to generate
692 random UUIDs. When editing events, e.g. using the HTML UI, only
693 the most recent event with the same UUID is shown. So when
694 updating events, be sure to apply the same UUID to the edited
695 copies before saving them.
696*/
697FSL_EXPORT int fsl_deck_E_set( fsl_deck * mf, double date, fsl_uuid_cstr uuid);
698
699/**
700 Adds a new F-card to the given deck. The uuid argument is required
701 to be NULL or pass the fsl_is_uuid() test. The name must be a
702 "simplified path name" (as determined by fsl_is_simple_pathname()),
703 or FSL_RC_RANGE is returned. Note that a NULL uuid is only valid
704 when constructing a delta manifest, and this routine will return
705 FSL_RC_MISUSE and update d->f's error state if uuid is NULL and
706 d->B.uuid is also NULL. Also returns FSL_RC_MISUSE if the name and
707 priorNames are the same.
708
709 perms should be one of the fsl_fileperm_e values (0 is the usual
710 case).
711
712 priorName must only be non-NULL when renaming a file, and it must
713 follow the same naming rules as the name parameter.
714
715 Returns 0 on success.
716
717 @see fsl_deck_F_set()
718*/
719FSL_EXPORT int fsl_deck_F_add( fsl_deck * d, char const * name,
720 fsl_uuid_cstr uuid,
721 fsl_fileperm_e perm,
722 char const * priorName);
723
724/**
725 Works mostly like fsl_deck_F_add() except that:
726
727 1) It enables replacing an existing F-card with a new one matching
728 the same name.
729
730 2) It enables removing an F-card by passing a NULL uuid.
731
732 3) It refuses to work on a deck for which d->uuid is not NULL or
733 d->rid!=0, returning FSL_RC_MISUSE if either of those apply.
734
735 If d contains no F-card matching the given name (case-sensitivity
736 depends on d->f's fsl_cx_is_case_sensitive() value) then:
737
738 - If the 3rd argument is NULL, it returns FSL_RC_NOT_FOUND with
739 (effectively) no side effects (aside, perhaps, from sorting d->F
740 if needed to perform the search).
741
742 - If the 3rd argument is not NULL then it behaves identically to
743 fsl_deck_F_add().
744
745 If a match is found, then:
746
747 - If the 3rd argument is NULL, it removes that entry from the
748 F-card list and returns 0.
749
750 - If the 3rd argument is not NULL, the fields of the resulting
751 F-card are modified to match the arguments passed to this
752 function, copying the values of all C-string arguments. (Sidebar:
753 we may need to copy the name, despite already knowing it, because
754 of how fsl_deck instances manage F-card memory.)
755
756 In all cases, if the 3rd argument is NULL then the 4th and 5th
757 arguments are ignored.
758
759 Returns 0 on success, FSL_RC_OOM if an allocation fails. See
760 fsl_deck_F_add() for other failure modes. On error, d's F-card list
761 may be left in an inconsistent state and it must not be used
762 further.
763
764 @see fsl_deck_F_add()
765 @see fsl_deck_F_set_content()
766*/
767FSL_EXPORT int fsl_deck_F_set( fsl_deck * d, char const * name,
768 fsl_uuid_cstr uuid,
769 fsl_fileperm_e perm,
770 char const * priorName);
771/**
772 UNDER CONSTRUCTION! EXPERIMENTAL!
773
774 This variant of fsl_deck_F_set() accepts a buffer of content to
775 store as the file's contents. Its hash is derived from that
776 content, using fsl_repo_blob_lookup() to hash the given content.
777 Thus this routine can replace existing F-cards and save their
778 content at the same time. When doing so, it will try to make the
779 parent version (if this is a replacement F-card) a delta of the new
780 content version (it may refuse to do so for various resources, but
781 any heuristics which forbid that will not trigger an error).
782
783 The intended use of this routine is for adding or replacing content
784 in a deck which has been prepared using fsl_deck_derive().
785
786 Returns 0 on success, else an error code propagated by
787 fsl_deck_F_set(), fsl_repo_blob_lookup(), or some other lower-level
788 routine. This routine requires that a transaction is active and
789 returns FSL_RC_MISUSE if none is active. For any non-trivial
790 error's, d->f's error state will be updated with a description of
791 the problem.
792
793 Returns FSL_RC_MISUSE if `d->rid>0` (which indicates that the deck
794 has already been saved in the repository). fsl_deck_derive() can be
795 used to "extend" a saved deck into a new version before using this API.
796
797 Returns FSL_RC_RANGE if zName is not a valid filename for use as a
798 repository entry, as per fsl_is_simple_pathname().
799
800 On error, d->f's error state will be updated with a description of
801 the problem.
802
803 TODO: add a fsl_cx-level or fsl_deck-level API for marking content
804 saved this way as private. This type of content is intended for use
805 cases which do not have a checkout, and thus cannot be processed
806 with fsl_checkin_commit() (which includes a flag to mark its
807 content as private).
808
809 @see fsl_deck_F_set()
810 @see fsl_deck_F_add()
811 @see fsl_deck_derive()
812*/
813FSL_EXPORT int fsl_deck_F_set_content( fsl_deck * d, char const * name,
814 fsl_buffer const * src,
815 fsl_fileperm_e perm,
816 char const * priorName);
817
818/**
819 UNDER CONSTRUCTION! EXPERIMENTAL!
820
821 This routine rewires d such that it becomes the basis for a derived
822 version of itself. Requires that d be a loaded from a repository,
823 complete with an RID, else FSL_RC_MISUSE is returned.
824
825 In short, this function performs the following:
826
827 - Clears d->P
828 - Assigns d->P[0] to the UUID of d->rid
829 - Clears d->rid
830 - Clears any other members which need to be (re)set by the new
831 child/derived version. That includes the following card
832 letters: `ACDEGHIJKLMNQRTUW`.
833 - If d is a delta manifest it restructures it as a new baseline
834 (see below).
835 - It specifically keeps d->F intact OR creates a new one (see below).
836
837 Returns 0 on success, FSL_RC_OOM on an allocation error,
838 FSL_RC_MISUSE if d->rid<=0 (i.e. the deck has never been saved or
839 was not loaded from the db). If d->type is not FSL_SATYPE_CHECKIN,
840 FSL_RC_TYPE is returned (fixing that for other derivable types is
841 TODO). On error, d may be left in an inconsistent state and must
842 not be used further except to pass it to fsl_deck_finalize().
843
844 The intention of this function is to simplify creation of decks
845 which are to be used for creating checkins without requiring a
846 checkout.
847
848 To avoid certain corner cases, this function does not allow
849 creation of delta manifests. If d has a B-card then it is a delta.
850 This function clears its B-card and recreates the F-card list using
851 the B-card's F-card list and any F-cards from the current delta. In
852 other words, it creates a new baseline manifest.
853
854 The expected workflow for this API is something like:
855
856 - Use fsl_deck_load_rid() to load a deck.
857 - Pass that deck to fsl_deck_derive().
858 - Update the deck's cards to suit.
859 - fsl_deck_save() the deck.
860
861 @todo Extend this to support other inheritable deck types, e.g.
862 wiki, forum posts, and technotes.
863
864 @see fsl_deck_F_set_content()
865*/
867
868/**
869 Callback type for use with fsl_deck_F_foreach() and
870 friends. Implementations must return 0 on success, FSL_RC_BREAK
871 to abort looping without an error, and any other value on error.
872*/
873typedef int (*fsl_card_F_visitor_f)(fsl_card_F const * fc,
874 void * state);
875
876/**
877 For each F-card in d, cb(card,visitorState) is called. Returns
878 the result of that loop. If cb returns FSL_RC_BREAK, the
879 visitation loop stops immediately and this function returns
880 0. If cb returns any other non-0 code, looping stops and that
881 code is returned immediately.
882
883 This routine calls fsl_deck_F_rewind() to reset the F-card cursor
884 and/or load d's baseline manifest (if any). If loading the baseline
885 fails, an error code from fsl_deck_baseline_fetch() is returned.
886
887 The F-cards will be visited in the order they are declared in
888 d. For loaded-from-a-repo manifests this is always lexical order
889 (for delta manifests, consistent across the delta and
890 baseline). For hand-created decks which have not yet been
891 fsl_deck_unshuffle()'d, the order is unspecified.
892*/
895 void * visitorState );
896
897/**
898 Fetches the next F-card entry from d. fsl_deck_F_rewind() must
899 have be successfully executed one time before calling this, as
900 that routine ensures that the baseline is loaded (if needed),
901 which is needed for proper iteration over delta manifests.
902
903 This routine always assigns *f to NULL before starting its work, so
904 the client can be assured that it will never contain the same value
905 as before calling this (unless that value was NULL).
906
907 On success 0 is returned and *f is assigned to the next F-card.
908 If *f is NULL when returning 0 then the end of the list has been
909 reached (fsl_deck_F_rewind() can be used to re-set it).
910
911 Example usage:
912
913 ```
914 int rc;
915 fsl_card_F const * fc = NULL;
916 rc = fsl_deck_F_rewind(d);
917 if(!rc) while( !(rc=fsl_deck_F_next(d, &fc)) && fc) {...}
918 ```
919
920 Note that files which were deleted in a given version are not
921 recorded in baseline manifests but are in deltas. To avoid
922 inconsistencies, this routine does NOT include deleted files in its
923 results, regardless of whether d is a baseline or delta. (It used
924 to, but that turned out to be a design flaw.)
925
926 Implementation notes: for baseline manifests this is a very
927 fast and simple operation. For delta manifests it gets
928 rather complicated.
929*/
931
932/**
933 Rewinds d's F-card traversal iterator and loads d's baseline
934 manifest, if it has one (i.e. if d->B.uuid is not NULL) and it is
935 not loaded already (i.e. if d->B.baseline is NULL). Returns 0 on
936 success. The only error condition is if loading of the a baseline
937 manifest fails, noting that only delta manifests have baselines.
938
939 Results are undefined if d->f is NULL, and that may trigger an
940 assert() in debug builds.
941*/
943
944/**
945 Looks for a file in a manifest or (for a delta manifest) its
946 baseline. No normalization of the given filename is performed -
947 it is assumed to be relative to the root of the checkout.
948
949 It requires that d->type be FSL_SATYPE_CHECKIN and that d be
950 loaded from a stored manifest or have been fsl_deck_unshuffle()'d
951 (if called on an under-construction deck). Specifically, this
952 routine requires that d->F be sorted properly or results are
953 undefined.
954
955 d->f is assumed to be the fsl_cx instance which deck was loaded
956 from, which impacts the search process as follows:
957
958 - The search take's d->f's underlying case-insensitive option into
959 account. i.e. if case-insensitivy is on then files in any case
960 will match.
961
962 - If no match is found in d and is a delta manifest (d->B.uuid
963 is set) then d's baseline is lazily loaded (if needed) and
964 the search continues there. (Delta manifests are only one level
965 deep, so this is not recursive.)
966
967 Returns NULL if !d, !d->f, or d->type!=FSL_SATYPE_CHECKIN, if no
968 entry is found, or if delayed loading of the parent manifest (if
969 needed) of a delta manifest fails (in which case d->f's error
970 state should hold more information about the problem).
971
972 In debug builds this function asserts that d is not NULL.
973
974 Design note: d "should" be const, but search optimizations for
975 the typical use case require potentially lazy-loading
976 d->B.baseline and updating d->F.
977*/
978FSL_EXPORT fsl_card_F const * fsl_deck_F_search(fsl_deck *d, const char *zName);
979
980/**
981 Given two F-card instances, this function compares their names
982 (case-sensitively). Returns a negative value if lhs is
983 lexically less than rhs, a positive value if lhs is lexically
984 greater than rhs, and 0 if they are lexically equivalent (or are
985 the same pointer).
986
987
988 Though fossil repositories may be case-insensitive, the F-cards use
989 a stable casing unless a file is removed and re-added with a
990 different case, so this comparison is case-sensitive..
991
992 Results are undefined if either argument is NULL.
993*/
995 fsl_card_F const * rhs);
996
997/**
998 If fc->uuid refers to a blob in f's repository database then that
999 content is placed into dest (as per fsl_content_get()) and 0 is
1000 returned. Returns FSL_RC_NOT_FOUND if fc->uuid is not
1001 found. Returns FSL_RC_MISUSE if any argument is NULL. If
1002 fc->uuid is NULL (indicating that it refers to a file deleted in
1003 a delta manifest) then FSL_RC_RANGE is returned. Returns
1004 FSL_RC_NOT_A_REPO if f has no repository opened.
1005
1006 On any error but FSL_RC_MISUSE (basic argument validation) f's
1007 error state is updated to describe the error.
1008
1009 @see fsl_content_get()
1010*/
1012 fsl_buffer * dest );
1013
1014/**
1015 Sets the 'G' card on a forum-post deck to a copy of the given
1016 UUID.
1017*/
1019/**
1020 Sets the 'H' card on a forum-post deck to a copy of the given
1021 comment. If cardLen is negative then fsl_strlen() is used to
1022 calculate its length.
1023 */
1024FSL_EXPORT int fsl_deck_H_set( fsl_deck * mf, char const * comment, fsl_int_t cardLen);
1025/**
1026 Sets the 'I' card on a forum-post deck to a copy of the given
1027 UUID.
1028*/
1030
1031/**
1032 Adds a J-card to the given deck, setting/updating the given ticket
1033 property key to the given value. The key is required but the value
1034 is optional (may be NULL). If isAppend then the value is appended
1035 to any existing value, otherwise it replaces any existing value.
1036
1037 It is currently unclear whether it is legal to include multiple
1038 J cards for the same key in the same control artifact, in
1039 particular if their isAppend values differ.
1040
1041 Returns 0 on success, FSL_RC_MISUSE if !mf or !key, FSL_RC_RANGE
1042 if !*field, FSL_RC_TYPE if mf is of a type for which J cards are
1043 not legal (see fsl_card_is_legal()), FSL_RC_OOM on allocation
1044 error.
1045*/
1046FSL_EXPORT int fsl_deck_J_add( fsl_deck * mf, bool isAppend,
1047 char const * key, char const * value );
1048
1049/**
1050 Sets the K-card (ticket ID) on the given deck. If passed NULL, it
1051 creates a new ticket ID (a 40-digit string of random hex bytes) and
1052 returns FSL_RC_OOM if allocation of those bytes fails. If uuid is
1053 not NULL then it must be a 40-byte lower-case hex string, the K-card
1054 value of the ticket this change is being applied to.
1055*/
1057
1058/**
1059 Semantically identical fsl_deck_B_set() but sets the L-card.
1060 title must be the wiki page title text of the wiki page this
1061 change is being applied to.
1062*/
1063FSL_EXPORT int fsl_deck_L_set( fsl_deck * mf, char const *title, fsl_int_t len);
1064
1065/**
1066 Adds the given UUID as an M-card entry. Returns 0 on success, or:
1067
1068 FSL_RC_MISUSE if !mf or !uuid
1069
1070 FSL_RC_TYPE if fsl_deck_check_type(mf,'M') returns false.
1071
1072 FSL_RC_RANGE if !fsl_is_uuid(uuid).
1073
1074 FSL_RC_OOM if memory allocation fails while adding the entry.
1075*/
1077
1078/**
1079 Semantically identical to fsl_deck_B_set() but sets the N card.
1080 mimeType must be the content mime type for comment text of the
1081 change being applied.
1082*/
1083FSL_EXPORT int fsl_deck_N_set( fsl_deck * mf, char const *mimeType, fsl_int_t len);
1084
1085/**
1086 Adds the given UUID as a parent of the given change record. If len
1087 is less than 0 then fsl_strlen(parentUuid) is used to determine its
1088 length. Returns FSL_RC_MISUE if !*parentUuid. Returns FSL_RC_RANGE
1089 if parentUuid does not pass fsl_is_uuid().
1090
1091 Results are undefined if parentUuid is NULL.
1092
1093 The first P-card added to a deck MUST be the UUID of its primary
1094 parent (one which was not involved in a merge operation). All
1095 others (from merges) are considered "non-primary."
1096
1097*/
1099/**
1100 A convenience wrapper around fsl_deck_P_add() which resolves the given
1101 RID to its UUID and passes it on to fsl_deck_P_add(). Returns non-0
1102 on error.
1103*/
1105
1106/**
1107 If d contains a P card with the given index, this returns the RID
1108 corresponding to the UUID at that index. Returns a negative value
1109 on error, 0 if there is no entry for that index (the index is out
1110 of bounds).
1111*/
1113
1114/**
1115 Adds a Q-card record to the given deck. The type argument must
1116 be negative for a backed-out change, positive for a cherrypicked
1117 change. target must be a valid UUID string. If baseline is not
1118 NULL then it also must be a valid UUID.
1119
1120 Returns 0 on success, non-0 on error. FSL_RC_MISUSE if !mf or
1121 !target, FSL_RC_SYNTAX if type is 0 or target/baseline are not
1122 valid UUID strings (baseline may be NULL).
1123*/
1125 fsl_uuid_cstr target,
1126 fsl_uuid_cstr baseline );
1127
1128/**
1129 Functionally identical to fsl_deck_B_set() except that it sets
1130 the R-card. Returns 0 on succes, FSL_RC_RANGE if md5 is not NULL
1131 or exactly FSL_STRLEN_MD5 bytes long (not including trailing
1132 NUL). If md5==NULL the current R value is cleared.
1133
1134 It would be highly unusual to have to set the R-card manually,
1135 as its calculation is quite intricate/intensive. See
1136 fsl_deck_R_calc() and fsl_deck_unshuffle() for details
1137*/
1138FSL_EXPORT int fsl_deck_R_set( fsl_deck * mf, char const *md5);
1139
1140/**
1141 Adds a new T-card (tag) entry to the given deck.
1142
1143 If uuid is not NULL and fsl_is_uuid(uuid) returns false then
1144 this function returns FSL_RC_RANGE. If uuid is NULL then it is
1145 assumed to be the UUID of the currently-being-constructed
1146 artifact in which the tag is contained (which appears as the '*'
1147 character in generated artifacts).
1148
1149 Returns 0 on success. Returns FSL_RC_MISUSE if !d or
1150 !name. Returns FSL_RC_TYPE (and update's d's error state with a
1151 message) if the T card is not legal for d (see
1152 fsl_card_is_legal()). Returns FSL_RC_RANGE if !*name, tagType
1153 is invalid, or if uuid is not NULL and fsl_is_uuid(uuid)
1154 return false. Returns FSL_RC_OOM if an allocation fails.
1155*/
1157 fsl_uuid_cstr uuid, char const * name,
1158 char const * value);
1159
1160/**
1161 Adds the given tag instance to the given manifest.
1162 Returns 0 on success, FSL_RC_MISUSE if either argument
1163 is NULL, FSL_RC_OOM if appending the tag to the list
1164 fails.
1165
1166 On success ownership of t is passed to mf. On error ownership is
1167 not modified.
1168*/
1170
1171/**
1172 A convenience form of fsl_deck_T_add() which adds two propagating
1173 tags to the given deck: "branch" with a value of branchName and
1174 "sym-branchName" with no value.
1175
1176 Returns 0 on success. Returns FSL_RC_OOM on allocation error and
1177 FSL_RC_RANGE if branchName is empty or contains any characters with
1178 ASCII values <=32d. It natively assumes that any characters >=128
1179 are part of multibyte UTF8 characters.
1180
1181 ACHTUNG: this does not arrange for canceling the previous branch
1182 because it doesn't know that branch at this point. To cancel the
1183 previous branch a cancelation T-card needs to be added to the deck
1184 named "sym-BRANCHNAME". Historically such tags have had the value
1185 "Cancelled by branch", but that's not a requirement.
1186*/
1187FSL_EXPORT int fsl_deck_branch_set( fsl_deck * d, char const * branchName );
1188
1189/**
1190 Calculates the value of d's R-card based on its F-cards and updates
1191 d->R. It may also, as a side-effect, sort d->F.list lexically (a
1192 requirement of a R-card calculation).
1193
1194 Returns 0 on success. Requires that d->f have an opened
1195 repository db, else FSL_RC_NOT_A_REPO is returned. If d's type is
1196 not legal for an R-card then FSL_RC_TYPE is returned and d->f's
1197 error state is updated with a description of the error. If d is of
1198 type FSL_SATYPE_CHECKIN and has no F-cards then the R-card's value
1199 is that of the initial MD5 hash state. Various other codes can be
1200 returned if fetching file content from the db fails.
1201
1202 Note that this calculation is exceedingly memory-hungry. While
1203 Fossil originally required R-cards, the cost of calculation
1204 eventually caused the R-card to be made optional. This API
1205 allows the client to decide on whether to use them (for more
1206 (admittedly redundant!) integrity checking) or not (much faster
1207 but "not strictly historically correct"), but defaults to having
1208 them enabled for symmetry with fossil(1).
1209
1210 @see fsl_deck_R_calc2()
1211*/
1213
1214/**
1215 A variant of fsl_deck_R_calc() which calculates the given deck's
1216 R-card but does not assign it to the deck, instead returning it
1217 via the 2nd argument:
1218
1219 If *tgt is not NULL when this function is called, it is required to
1220 point to at least FSL_STRLEN_MD5+1 bytes of memory to which the
1221 NUL-terminated R-card hash will be written. If *tgt is NULL then
1222 this function assigns (on success) *tgt to a dynamically-allocated
1223 R-card hash and transfers ownership of it to the caller (who must
1224 eventually fsl_free() it). On error, *tgt is not modified.
1225
1226 Results are undefined if either argument is NULL.
1227
1228 Returns 0 on success. See fsl_deck_R_calc() for information about
1229 possible errors, with the addition that FSL_RC_OOM is returned
1230 if *tgt is NULL and allocating a new *tgt value fails.
1231
1232 Calculating the R-card necessarily requires that d's F-card list be
1233 sorted, which this routine does if it seems necessary. The
1234 calculation also necessarily mutates the deck's F-card-traversal
1235 cursor, which requires loading the deck's B-card, if it has
1236 one. Aside from the F-card sorting, and potentially B-card, and the
1237 cursor resets, this routine does not modify the deck. On success,
1238 the deck's F-card iteration cursor (and that of d->B, if it's
1239 loaded) is rewound.
1240*/
1242
1243/**
1244 Semantically identical fsl_deck_B_set() but sets the U-card.
1245 userName must be the user who's name should be recorded for
1246 this change.
1247*/
1248FSL_EXPORT int fsl_deck_U_set( fsl_deck * mf, char const *userName);
1249
1250/**
1251 Semantically identical fsl_deck_B_set() but sets the W-card.
1252 content must be the page content of the Wiki page or Event this
1253 change is being applied to.
1254*/
1255FSL_EXPORT int fsl_deck_W_set( fsl_deck * mf, char const *content, fsl_int_t len);
1256
1257/**
1258 Must be called to initialize a newly-created/allocated deck
1259 instance. This function clears out all contents of the d
1260 parameter except for its (f, type, allocStamp) members, sets its
1261 (f, type) members, and leaves d->allocStamp intact.
1262
1263 Note that, prior to calling this, the deck _must_ have been cleanly
1264 initialized via copying from fsl_deck_empty or (depending on the
1265 context) fsl_deck_empty_m or results are undefined.
1266*/
1268 fsl_satype_e type );
1269
1270/**
1271 Returns true if d contains data for all _required_ cards, as
1272 determined by the value of d->type, else returns false. It returns
1273 false if d->type==FSL_SATYPE_ANY, as that is a placeholder value
1274 intended to be re-set by the deck's user.
1275
1276 If it returns false, d->f's error state will help a description of
1277 the problem.
1278
1279 The library calls this as needed, but clients may, if they want
1280 to. Note, however, that for FSL_SATYPE_CHECKIN decks it may fail
1281 if the deck has not been fsl_deck_unshuffle()d yet because the
1282 R-card gets calculated there (if needed).
1283
1284 As a special case, d->f is configured to calculate R-cards,
1285 d->type==FSL_SATYPE_CHECKIN, AND d->R is not set, this will fail
1286 (with a descriptive error message).
1287
1288 Another special case: for FSL_SATYPE_CHECKIN decks, if no
1289 F-cards are in th deck then an R-card is required to avoid a
1290 potental (admittedly harmless) syntactic ambiguity with
1291 FSL_SATYPE_CONTROL artifacts. The only legal R-card for a
1292 checkin with no F-cards has the initial MD5 hash state value
1293 (defined in the constant FSL_MD5_INITIAL_HASH), and that
1294 precondition is checked in this routine. fsl_deck_unshuffle()
1295 recognizes this case and adds the initial-state R-card, so
1296 clients normally need not concern themselves with this. If d has
1297 F-cards, whether or not an R-card is required depends on
1298 whether d->f is configured to require them or not.
1299
1300 Enough about the R-card. In all other cases not described above,
1301 R-cards are not required (and they are only ever required on
1302 FSL_SATYPE_CHECKIN manifests).
1303
1304 Though fossil(1) does not technically require F-cards in
1305 FSL_SATYPE_CHECKIN decks, so far none of the Fossil developers
1306 have found a use for a checkin without F-cards except the
1307 initial empty checkin. Additionally, a checkin without F-cards
1308 is potentially syntactically ambiguous (it could be an EVENT or
1309 ATTACHMENT artifact if it has no F- or R-card). So... this
1310 library _normally_ requires that CHECKIN decks have at least one
1311 F-card. This function, however, does not consider F-cards to be
1312 strictly required.
1313*/
1315
1316/**
1317 Prepares the given deck for output by ensuring that cards
1318 which need to be sorted are sorted, and it may run some
1319 last-minute validation checks.
1320
1321 The cards which get sorted are: F, J, M, Q, T. The P-card list is
1322 _not_ sorted - the client is responsible for ensuring that the
1323 primary parent is added to that list first, and after that the
1324 ordering is largely irrelevant. It is not possible for the library
1325 to determine a proper order for P-cards, nor to validate that order
1326 at input-time.
1327
1328 If calculateRCard is true and fsl_card_is_legal(d,'R') then this
1329 function calculates the R-card for the deck. The R-card
1330 calculation is _extremely_ memory-hungry but adds another level
1331 of integrity checking to Fossil. If d->type is not
1332 FSL_SATYPE_MANIFEST then calculateRCard is ignored.
1333
1334 If calculateRCard is true but no F-cards are present AND d->type is
1335 FSL_SATYPE_CHECKIN then the R-card is set to the initial MD5 hash
1336 state (the only legal R-card value for an empty F-card list). (This
1337 is necessary in order to prevent a deck-type ambiguity in one
1338 corner case.)
1339
1340 The R-card, if used, must be calculated before
1341 fsl_deck_output()ing a deck containing F-cards. Clients may
1342 alternately call fsl_deck_R_calc() to calculate the R card
1343 separately, but there is little reason to do so. There are rare
1344 cases where the client can call fsl_deck_R_set()
1345 legally. Historically speaking the R-card was required when
1346 F-cards were used, but it was eventually made optional because
1347 (A) the memory cost and (B) it's part of a 3rd or 4th level of
1348 integrity-related checks, and is somewhat superfluous.
1349
1350 @see fsl_deck_output()
1351 @see fsl_deck_save()
1352*/
1353FSL_EXPORT int fsl_deck_unshuffle( fsl_deck * d, bool calculateRCard );
1354
1355/**
1356 Renders the given control artifact's contents to the given output
1357 function and calculates any cards which cannot be calculated until
1358 the contents are complete (namely the R-card and Z-card).
1359
1360 If both (output, outputState) are NULL then d->f's outputer is
1361 used.
1362
1363 The given deck is "logically const" but traversal over F-cards and
1364 baselines requires non-const operations. To keep this routine from
1365 requiring an undue amount of pre-call effort on the client's part,
1366 it also takes care of calling fsl_deck_unshuffle() to ensure that
1367 all of the deck's cards are in order. (If the deck has no R card,
1368 but has F-cards, and d->f is configured to generate R-cards, then
1369 unshuffling will also calculate the R-card.)
1370
1371 Returns 0 on success, FSL_RC_MISUSE if !d or !d->f or !out. If
1372 out() returns non-0, output stops and that code is
1373 returned. outputState is passed as the first argument to out() and
1374 out() may be called an arbitrary number of times by this routine.
1375
1376 Returns FSL_RC_SYNTAX if fsl_deck_has_required_cards()
1377 returns false.
1378
1379 On errors more serious than argument validation, the deck's
1380 context's (d->f) error state is updated.
1381
1382 The exact structure of the ouput depends on the value of
1383 d->type, and FSL_RC_TYPE is returned if this function cannot
1384 figure out what to do with the given deck's type.
1385
1386 @see fsl_deck_unshuffle()
1387 @see fsl_deck_save()
1388*/
1390 void * outputState);
1391
1392/**
1393 Emits a JSON representation of the given deck to the given output
1394 routine. Returns 0 on success, non-0 on error. Any error codes,
1395 aside from FSL_RC_OOM, will have come from the given callback.
1396
1397 The output is intended to be compatible with fossil(1)'
1398 artifact_to_json() (any deviation is a bug). The output is compact,
1399 not nicely-formatted. It can be sent to sqlite's json_pretty() to
1400 format it.
1401
1402 If d->rid<=0, e.g. because it was just processed by
1403 fsl_deck_parse(), the resulting JSON object will have a "uuid" of
1404 null. If that property is important, it is up to the caller to set
1405 it before calling this.
1406*/
1407FSL_EXPORT int fsl_deck_to_json(fsl_deck const * d, fsl_output_f fn, void * fState);
1408
1409/**
1410 Saves the given deck into f's repository database as new control
1411 artifact content. If isPrivate is true then the content is
1412 marked as private, otherwise it is not. Note that isPrivate is a
1413 suggestion and might be trumped by existing state within f or
1414 its repository, and such a trumping is not treated as an
1415 error. e.g. tags are automatically private when they tag private
1416 content.
1417
1418 Before saving, the deck is passed through fsl_deck_unshuffle()
1419 and fsl_deck_output(), which will fail for a variety of
1420 easy-to-make errors such as the deck missing required cards.
1421 For unshuffle purposes, the R-card gets calculated if the deck
1422 has any F-cards AND if the caller has not already set/calculated
1423 it AND if f's FSL_CX_F_CALC_R_CARD flag is set (it is on by
1424 default for historical reasons, but this may change at some
1425 point).
1426
1427 Returns 0 on success, the usual non-0 suspects on error.
1428
1429 - If d->rid is positive, it is assumed to refer to a valid
1430 `blob.rid` and this function returns 0 without side-effects. It
1431 does _not_ attempt to re-save such a record, as that could very
1432 possible result in a new hash (and would definitely do so if the
1433 deck's state had been modified in the slightest bit (literally
1434 "bit")). It should arguably return FSL_RC_ALREADY_EXISTS for this
1435 case, but does not do so for historical reasons.
1436
1437 - PREVIOUSLY (prior to 2021-10-20), we assumed such a deck referred
1438 to a phantom which we would then save, but that behaviour seems to
1439 be misguided, as we only ever want to save newly-created decks, not
1440 decks created from existing content.
1441
1442 On success, d->rid be set to the new record's RID. It will only be
1443 set on success because it would otherwise refer to a db record
1444 which get destroyed when the transaction rolls back.
1445
1446 After saving, the deck will be cross-linked to update any
1447 relationships described by the deck.
1448
1449 The save operation happens within a transaction, of course, and
1450 on any sort of error, db-side changes are rolled back. Note that
1451 it _is_ legal to start the transaction before calling this,
1452 which effectively makes this operation part of that transaction.
1453
1454 This function will fail with FSL_RC_ACCESS if d is a delta manifest
1455 (has a B-card) and d->f's forbid-delta-manifests configuration
1456 option is set to a truthy value. See
1457 fsl_repo_forbids_delta_manifests().
1458
1459 Maintenance reminder: this function also does a very small bit of
1460 artifact-type-specific processing.
1461
1462 @see fsl_deck_output()
1463*/
1464FSL_EXPORT int fsl_deck_save( fsl_deck * d, bool isPrivate );
1465
1466/**
1467 Parses src as Control Artifact content and populates d with it.
1468
1469 d will be cleaned up before parsing if it has any contents,
1470 retaining its d->f member (which must be set to non-NULL by the
1471 caller for error-reporting purposes).
1472
1473 This function _might_ take over the contents of the source
1474 buffer. If it does, after returning src->mem will be NULL, and all
1475 other members will be reset to their default state. This function
1476 only takes over the contents if it decides to implement certain
1477 memory optimizations.
1478
1479 Ownership of src itself is never changed by this function, only
1480 the ownership of its contents. On success, this function always
1481 clears the buffer's contents, possibly (but not necessarily)
1482 transfering ownership of them to the deck.
1483
1484 In any case, the content of the source buffer is (normally)
1485 modified by this function because (A) that simplifies tokenization
1486 greatly, (B) saves us having to make another copy to work on, (C)
1487 the original implementation did it that way, (D) because in
1488 historical use the source is normally thrown away after parsing,
1489 anyway, and (E) in combination with taking ownership of src's
1490 contents it allows us to optimize away some memory allocations by
1491 re-using the internal memory of the buffer. This function never
1492 changes src's size, but it mutilates its contents (injecting NUL
1493 bytes as token delimiters).
1494
1495 If d->type is _not_ FSL_SATYPE_ANY when this is called, then
1496 this function requires that the input to be of that type. We can
1497 fail relatively quickly in that case, and this can be used to
1498 save some downstream code some work. Note that the initial type
1499 for decks created using fsl_deck_malloc() or copy-initialized
1500 from ::fsl_deck_empty is FSL_SATYPE_ANY, so normally clients do
1501 not need to set this (unless they want to, as a small
1502 optimization).
1503
1504 On success it returns 0 and d will be updated with the state from
1505 the input artifact and the contents of the source buffer will
1506 either be cleared or taken over by d. (Ideally, outputing d via
1507 fsl_deck_output() will produce a lossless copy of the original, but
1508 timestamp granularity might prevent that.)
1509
1510 On error, if there is error information to propagate beyond the
1511 result code then it is stored in d->f. Whether or not such error
1512 info is propagated depends on the type of error, but anything more
1513 trivial than invalid arguments will be noted there. On error, the
1514 source buffer's contents _might_, depending on which phase the
1515 error happened, be left in place but may have been modified by the
1516 parsing process. If the error happens after _certain_ parsing
1517 steps then the deck will be required to take over the buffer's
1518 memory in order to keep memory management sane. On error, clients
1519 should always eventually pass the source buffer to
1520 fsl_buffer_clear(). On success its contents are guaranteed to have
1521 been cleared or or transfered to the destination deck when this
1522 function returns.
1523
1524 d might be partially populated on error, so regardless of success
1525 or failure, the client must eventually pass d to
1526 fsl_deck_finalize() to free its memory.
1527
1528 Error result codes include:
1529
1530 - FSL_RC_SYNTAX on syntax errors. Fossil's tried-and-true approach
1531 to determine "is this an artifact?" is "can it pass through
1532 fsl_deck_parse()?" This result code simply means that the input
1533 is, strictly speaking, not a fossil artifact. In some contexts
1534 this condition must be caught and treated as not-an-error (but
1535 also not an artifact).
1536
1537 - FSL_RC_MISUSE if any pointer argument is NULL or d->f is NULL.
1538
1539 - FSL_RC_CONSISTENCY if validation of a Z-card fails. This is a
1540 more specialized form of FSL_RC_SYNTAX but indicates that the
1541 artifact is (or may be) well-formed but has an incorrect hash.
1542 This check happens relatively early in the parsing process, but
1543 after this function has uses fsl_might_be_artifact() to do a
1544 basic sniff-test. In practice, this error "cannot happen" unless
1545 the source buffer has been manually manipulated. Whether or not
1546 client-side code wants to treat this as FSL_RC_SYNTAX (i.e. "not
1547 an artifact but not an error") is up to the client
1548
1549 - Any number of errors coming from the allocator, database, or
1550 fsl_deck APIs used here.
1551
1552 ACHTUNG API CHANGE: prior to 2021-10-20, this routine set d->rid
1553 (and the now-removed d->uuid) based on the hash of the input buffer
1554 if a matching record could be found in the db. That proved to be
1555 a huge performance hit and was removed.
1556
1557 Maintenance reminder: in keeping with fossil's "if it quacks like
1558 an artifact, it is an artifact, else it's not" approach to
1559 determining whether opaque blobs are artifacts, this function
1560 _must_ continue to return FSL_RC_SYNTAX to indicate that "it
1561 doesn't quack like an artifact but there's otherwise nothing
1562 wrong," which downstream code must be able to rely upon as the
1563 input being a non-artifact. More serious errors, e.g. FSL_RC_OOM,
1564 are (of course) to be propagated back.
1565
1566 @see fsl_deck_parse2()
1567*/
1569
1570/**
1571 This variant of fsl_deck_parse() works identically to that
1572 function except for the 3rd argument.
1573
1574 If you happen to know the _correct_ RID for the deck being parsed,
1575 pass it as the rid argument, else pass 0. A negative value will
1576 result in a FSL_RC_RANGE error. This value is (or may be) only
1577 used as an optimization in this function and/or downstream
1578 functions. Passing a positive value will cause d->f to do a cache
1579 lookup which may avoid it having to parse the deck at all.
1580*/
1582
1583/**
1584 Quickly determines whether the content held by the given buffer
1585 "might" be a structural artifact. It performs a fast sanity check
1586 for prominent features which can be checked either in O(1) or very
1587 short O(N) time (with a fixed N). If it returns false then the
1588 given buffer's contents are, with 100% certainty, _not_ a
1589 structural artifact. If it returns true then they _might_ be, but
1590 being 100% certain requires passing the contents to
1591 fsl_deck_parse() to fully parse them.
1592*/
1594
1595/**
1596 Loads the content from given rid and tries to parse it as a
1597 Fossil artifact. If rid==0 the current checkout (if opened) is
1598 used. (Trivia: there can never be a checkout with rid==0 but
1599 rid==0 is sometimes valid for an new/empty repo devoid of
1600 commits.) If type==FSL_SATYPE_ANY then it will allow any type of
1601 control artifact, else it returns FSL_RC_TYPE if the loaded
1602 artifact is of the wrong type.
1603
1604 Returns 0 on success. Results are undefined if f or d are NULL. The
1605 potential error result codes include, but are not limited to:
1606
1607 - FSL_RC_OOM
1608
1609 - FSL_RC_RANGE if rid is negative or is 0 and no checkout is
1610 opened.
1611
1612 - FSL_RC_TYPE if `type` is not `FSL_SATYPE_ANY` and the loaded
1613 result is of any artifact type other than `type`.
1614
1615 d must be properly initialized, either copy-initialized from
1616 fsl_deck_empty or populated by the library's API. This function
1617 will (re)initialize it and may leave it partially populated on
1618 error. The caller must eventually pass it to fsl_deck_finalize()
1619 resp. fsl_deck_clean() regardless of success or error. This
1620 function "could" clean it up on error, but leaving it partially
1621 populated makes debugging easier.
1622
1623 f's error state may be updated on error (for anything more
1624 serious than basic argument validation errors).
1625
1626 On success this function sets d->rid to rid.
1627
1628 @see fsl_deck_load_sym()
1629*/
1631 fsl_id_t rid, fsl_satype_e type );
1632
1633/**
1634 A convenience form of fsl_deck_load_rid() which uses
1635 fsl_sym_to_rid() to convert symbolicName into an artifact RID. See
1636 fsl_deck_load_rid() for the symantics of the first, second, and
1637 fourth arguments, as well as the return value. See fsl_sym_to_rid()
1638 for the allowable values of symbolicName.
1639
1640 @see fsl_deck_load_rid()
1641*/
1643 char const * symbolicName,
1644 fsl_satype_e type );
1645
1646/**
1647 Loads the baseline manifest specified in d->B.uuid, if any and if
1648 necessary. Returns 0 on success. If d->B.baseline is already loaded
1649 or d->B.uuid is NULL (in which case there is no baseline), it
1650 returns 0 and has no side effects.
1651
1652 Neither argument may be NULL and d must be a fully-populated
1653 object, complete with a proper d->rid, before calling this.
1654
1655 On success 0 is returned. If d->B.baseline is NULL then
1656 it means that d has no baseline manifest (and d->B.uuid will be NULL
1657 in that case). If d->B.baseline is not NULL then it is owned by
1658 d and will be cleaned up when d is cleaned/finalized.
1659
1660 Error codes include, but are not limited to:
1661
1662 - FSL_RC_MISUSE if !d->f.
1663
1664 - FSL_RC_NOT_A_REPO if d->f has no opened repo db.
1665
1666 - FSL_RC_RANGE if d->rid<=0, but that code might propagate up from
1667 a lower-level call as well.
1668
1669 On non-trivial errors d->f's error state will be updated to hold
1670 a description of the problem.
1671
1672 Some misuses trigger assertions in debug builds.
1673*/
1675
1676/**
1677 A callback interface for manifest crosslinking, so that we can farm
1678 out the updating of the event table (and similar bookkeeping) as
1679 manifests are crosslinked. Each callback registered via
1680 fsl_xlink_listener() will be called at the end of the so-called
1681 crosslinking process, which is run every time an artifact is
1682 processed for d->f's repository database, passed the deck being
1683 crosslinked and the client-provided state which was registered with
1684 fsl_xlink_listener(). Note that the deck object itself holds other
1685 state useful for crosslinking, like the blob.rid value of the deck
1686 and its fsl_cx instance.
1687
1688 If an implementation is only interested in a specific type of
1689 artifact, it must check d->type and return 0 if it's an
1690 "uninteresting" type.
1691
1692 Implementations must return 0 on success or some other fsl_rc_e
1693 value on error. Returning non-0 causes the database transaction
1694 for the crosslinking operation to roll back, effectively
1695 cancelling whatever pending operation triggered the
1696 crosslink. If any callback fails, processing stops immediately -
1697 no other callbacks are executed.
1698
1699 Implementations which want to report more info than an integer
1700 should call fsl_cx_err_set() to set d->f's error state, as that
1701 will be propagated up to the code which initiated the failed
1702 crosslink.
1703
1704 ACHTUNG and WARNING: the fsl_deck parameter "really should" be
1705 const, but certain operations on a deck are necessarily non-const
1706 operations. That includes, but may not be limited to:
1707
1708 - Iterating over F-cards, which requires calling
1709 fsl_deck_F_rewind() before doing so. Traversal of F-cards
1710 internally uses a necessarily-mutable cursor.
1711
1712 - Loading a checkin's baseline (required for F-card iteration and
1713 performed automatically by fsl_deck_F_rewind()).
1714
1715 Aside from such iteration-related mutable state, it is STRICTLY
1716 ILLEGAL to modify a deck's artifact-related state while it is
1717 undergoing crosslinking. Violating that will lead to undefined
1718 results.
1719
1720 Potential TODO: add some client-opaque state to decks so that they
1721 can be flagged as "being crosslinked" and fail mutation operations
1722 such as card adders/setters.
1723
1724 @see fsl_xlink_listener()
1725*/
1726typedef int (*fsl_deck_xlink_f)(fsl_deck * d, void * state);
1727
1728/**
1729 A type for holding state for artifact crosslinking callbacks.
1730*/
1732 /** Human-readable name of the crosslinker, noting that each
1733 registered crosslinker must have a unique name. Registering a
1734 crosslinker with the same name as an existing one replaces that
1735 one.
1736 */
1737 char const * name;
1738 /** Callback function. */
1740 /** State for this->f's last argument. */
1741 void * state;
1742};
1744
1745/** Empty-initialized fsl_xlinker struct, intended for const-copy
1746 intialization. */
1747#define fsl_xlinker_empty_m {NULL,NULL,NULL}
1748
1749/** Empty-initialized fsl_xlinker struct, intended for copy intialization. */
1750extern const fsl_xlinker fsl_xlinker_empty;
1751
1752/**
1753 A list of fsl_xlinker instances.
1754*/
1756 /** Number of used items in this->list. */
1758 /** Number of slots allocated in this->list. */
1760 /** Array of this->used elements. */
1762};
1764
1765/** Empty-initializes fsl_xlinker_list struct, intended for
1766 const-copy intialization. */
1767#define fsl_xlinker_list_empty_m {0,0,NULL}
1768
1769/** Empty-initializes fsl_xlinker_list struct, intended for copy intialization. */
1771
1772/**
1773 Searches f's crosslink callbacks for an entry with the given
1774 name and returns that entry, or NULL if no match is found. The
1775 returned object is owned by f.
1776*/
1777fsl_xlinker * fsl_xlinker_by_name( fsl_cx * f, char const * name );
1778
1779/**
1780 Adds the given function as a "crosslink callback" for the given
1781 Fossil context. The callback is called at the end of a successful
1782 "artifact crosslink" operation and provides a way for the client to
1783 perform their own work based on the app having crosslinked an
1784 artifact. Crosslinking happens when artifacts are saved or upon a
1785 rebuild operation.
1786
1787 This function returns 0 on success, non-0 on error. Behaviour is
1788 undefined if any of the first 3 arguments are NULL.
1789
1790 Crosslink callbacks are called at the end of the core crosslink
1791 steps, in the order they are registered, with the caveat that if a
1792 listener is overwritten by another with the same name, the new
1793 entry retains the older one's position in the list. The library may
1794 register its own before the client gets a chance to.
1795
1796 If _any_ crosslinking callback fails (returns non-0) then the
1797 _whole_ crosslinking fails and is rolled back (which may very
1798 well include pending tags/commits/whatever getting rolled back).
1799
1800 The state parameter has no meaning for this function, but is
1801 passed on as the final argument to cb(). If not NULL, cbState
1802 "may" be required to outlive f, depending on cbState's exact
1803 client-side internal semantics/use, as there is currently no API
1804 to remove registered crosslink listeners.
1805
1806 The name must be non-NULL/empty. If a listener is registered with a
1807 duplicate name then the first one is replaced. This function does
1808 not copy the name bytes - they are assumed to be static or
1809 otherwise to live at least as long as f. The name may be
1810 arbitrarily long, but must have a terminating NUL byte. It is
1811 recommended that clients choose a namespace/prefix to apply to the
1812 names they register. The library reserves the prefix "fsl/" for
1813 its own use, and will happily overwrite client-registered entries
1814 with the same names. The name string need not be stable across
1815 application sessions and maybe be a randomly-generated string.
1816
1817 Caveat: some obscure artifact crosslinking steps do not happen
1818 unless crosslinking takes place in the context of a
1819 fsl__crosslink_begin() and fsl__crosslink_end()
1820 session. Thus, at the time client-side crosslinker callbacks are
1821 called, certain crosslinking state in the database may still be
1822 pending. It is as yet unclear how best to resolve that minor
1823 discrepancy, or whether it even needs resolving.
1824
1825 As a rule, it is important that crosslink handler checks the
1826 deck->type field of the deck they are passed, and return 0, without
1827 side effects, if the type is not specifically handled by that
1828 handler. Every crosslink handler is passed every crosslinked
1829 artifact, but it's rare for crosslink handlers to handle more than
1830 one type of artifact, except perhaps for purposes of notifying a
1831 user that some progress is being made.
1832
1833 Default (overrideable) crosslink handlers:
1834
1835 The library internally splits crosslinking of artifacts into two
1836 parts: the main one (which clients cannot modify) handles the
1837 database-level linking of relational state implied by a given
1838 artifact. The secondary one adds an entry to the "event" table,
1839 which is where Fossil's timeline lives. The crosslinkers for the
1840 timeline updates may be overridden by clients by registering
1841 a crosslink listener with the following names:
1842
1843 - Attachment artifacts: "fsl/attachment/timeline"
1844
1845 - Checkin artifacts: "fsl/checkin/timeline"
1846
1847 - Control artifacts: "fsl/control/timeline"
1848
1849 - Forum post artifacts: "fsl/forumpost/timeline"
1850
1851 - Technote artifacts: "fsl/technote/timeline"
1852
1853 - Wiki artifacts: "fsl/wiki/timeline"
1854
1855 A context registers listeners under those names when it
1856 initializes, and clients may override them at any point after that.
1857
1858 Sidebar: due to how tickets are crosslinked (_after_ the general
1859 crosslinking phase is actually finished and requiring state which
1860 other crosslinkers do not), it is not currently possible to
1861 override the ticket crosslink handler. Thus the core ticket
1862 crosslinker will always run, and update the [event] table, but a
1863 custom crosslinker may overwrite the resulting [event] table
1864 entries (in particular, the comment). Determining whether/how
1865 ticket crosslinking can be restructured to be consistent with the
1866 other types is on the TODO list.
1867
1868 Caveat: updating the timeline requires a bit of knowledge about the
1869 Fossil DB schema and/or conventions. Updates for certain types,
1870 e.g. attachment/control/forum post, is somewhat more involved and
1871 updating the timeline for wiki comments requires observing a "quirk
1872 of conventions" for labeling such comments, such that they will
1873 appear properly when the main fossil app renders them. That said,
1874 the only tricky parts of those updates involve generating the
1875 "correct" comment text. So long as the non-comment parts are
1876 updated properly (that part is easy to do), fossil can function
1877 with it. The timeline comment text/links are soley for human
1878 consumption. Fossil makes much use of the "event" table internally,
1879 however, so the rest of that table must be properly populated.
1880
1881 Because of that caveat, clients may, rather than overriding the
1882 defaults, install their own crosslink listners which ammend the
1883 state applied by the default ones. e.g. add a listener which
1884 watches for checkin updates and replace the default-installed
1885 comment with one suitable for your application, leaving the rest of
1886 the db state in place. At its simplest, that looks more or less
1887 like the following code (inside a fsl_deck_xlink_f() callback):
1888
1889 ```
1890 int rc = fsl_db_exec(fsl_cx_db_repo(deck->f),
1891 "UPDATE event SET comment=%Q "
1892 "WHERE objid=%"FSL_ID_T_PFMT,
1893 "the new comment.", deck->rid);
1894 ```
1895*/
1896FSL_EXPORT int fsl_xlink_listener( fsl_cx * f, char const * name,
1897 fsl_deck_xlink_f cb, void * cbState );
1898
1899
1900/**
1901 For the given blob.rid value, returns the blob.size value of
1902 that record via *rv. Returns 0 or higher on success, -1 if a
1903 phantom record is found, -2 if no entry is found, or a smaller
1904 negative value on error (dig around the sources to decode them -
1905 this is not expected to fail unless the system is undergoing a
1906 catastrophe).
1907
1908 @see fsl_content_raw()
1909 @see fsl_content_get()
1910 @see fsl_content_size_v2()
1911*/
1913
1914/**
1915 Given a blob RID, this function extracts its size from the
1916 `blob.rid` db field. On success, returns 0 and sets *pOut to
1917 the new size. Negative sizes mean the blob is a "phantom."
1918
1919 On error it returns non-0 and updates f's error state.
1920
1921 @see fsl_content_size()
1922*/
1924 fsl_int_t *pOut);
1925
1926/**
1927 For the given blob.rid value, fetches the content field of that
1928 record and overwrites tgt's contents with it (reusing tgt's
1929 memory if it has any and if it can). The blob's contents are
1930 uncompressed if they were stored in compressed form. This
1931 extracts a raw blob and does not apply any deltas - use
1932 fsl_content_get() to fully expand a delta-stored blob.
1933
1934 By and large, client-side code will want fsl_content_get() over
1935 this functino.
1936
1937 Returns 0 on success. On error tgt might be partially updated,
1938 e.g. it might be populated with compressed data instead of
1939 uncompressed. On error tgt's contents should be recycled
1940 (e.g. fsl_buffer_reuse()) or discarded (e.g. fsl_buffer_clear()) by
1941 the client. Returns FSL_RC_RANGE if blobRid<=0, FSL_RC_NOT_A_REPO
1942 if f has no repo opened, FSL_RC_OOM on allocation error, or
1943 potentially any number of other codes via the db layer.
1944
1945 Results are undefined if any pointer argument is NULL.
1946
1947 @see fsl_content_get()
1948 @see fsl_content_size()
1949*/
1951 fsl_buffer * tgt );
1952
1953/** @deprecated
1954
1955 Older (deprecated) name of fsl_content_raw().
1956*/
1957#define fsl_content_blob fsl_content_raw
1958
1959/**
1960 Functionally similar to fsl_content_raw() but does a lot of
1961 work to ensure that the returned blob is expanded from its
1962 deltas, if any. The tgt buffer's memory, if any, will be
1963 replaced/reused if it has any.
1964
1965 Returns 0 on success. There are no less than 50 potental
1966 different errors, so we won't bother to list them all. On error
1967 tgt might be partially populated. The basic error cases are:
1968
1969 - FSL_RC_MISUSE if !tgt or !f.
1970
1971 - FSL_RC_RANGE if rid<=0 or if an infinite loop is discovered in
1972 the repo delta table links (that is a consistency check to avoid
1973 an infinite loop - that condition "cannot happen" because the
1974 verify-before-commit logic catches that error case).
1975
1976 - FSL_RC_NOT_A_REPO if f has no repo db opened.
1977
1978 - FSL_RC_NOT_FOUND if the given rid is not in the repo db.
1979
1980 - FSL_RC_OOM if an allocation fails.
1981
1982
1983 @see fsl_content_raw()
1984 @see fsl_content_size()
1985*/
1987 fsl_buffer * tgt );
1988
1989/**
1990 Uses fsl_sym_to_rid() to convert sym to a record ID, then
1991 passes that to fsl_content_get(). Returns 0 on success.
1992*/
1993FSL_EXPORT int fsl_content_get_sym( fsl_cx * f, char const * sym,
1994 fsl_buffer * tgt );
1995
1996/**
1997 Returns true if the given rid is marked as PRIVATE in f's current
1998 repository. Returns false (0) on error or if the content is not
1999 marked as private.
2000*/
2002
2003/**
2004 Marks the given rid public, if it was previously marked as
2005 private. Returns 0 on success, non-0 on error.
2006
2007 Note that it is not possible to make public content private.
2008*/
2010
2011/**
2012 Generic callback interface for visiting decks. The interface
2013 does not generically require that d survive after this call
2014 returns.
2015
2016 Implementations must return 0 on success, non-0 on error. Some
2017 APIs using this interface may specify that FSL_RC_BREAK can be
2018 used to stop iteration over a loop without signaling an error.
2019 In such cases the APIs will translate FSL_RC_BREAK to 0 for
2020 result purposes, but will stop looping over whatever it is they
2021 are looping over.
2022
2023 Note that the passed-in deck "should" be const but is not because
2024 iterating over a deck's F-cards requires non-const state.
2025*/
2026typedef int (*fsl_deck_visitor_f)( fsl_cx * f, fsl_deck * d,
2027 void * state );
2028
2029/**
2030 For each unique wiki page name in f's repostory, this calls
2031 cb(), passing it the manifest of the most recent version of that
2032 page. The callback should return 0 on success, FSL_RC_BREAK to
2033 stop looping without an error, or any other non-0 code
2034 (preferably a value from fsl_rc_e) on error.
2035
2036 The 3rd parameter has no meaning for this function but it is
2037 passed on as-is to the callback.
2038
2039 ACHTUNG: the deck passed to the callback is transient and will
2040 be cleaned up after the callback has returned, so the callback
2041 must not hold a pointer to it or its contents.
2042
2043 @see fsl_wiki_load_latest()
2044 @see fsl_wiki_latest_rid()
2045 @see fsl_wiki_names_get()
2046 @see fsl_wiki_page_exists()
2047*/
2049
2050/**
2051 Fetches the most recent RID for the given wiki page name and
2052 assigns *newId (if it is not NULL) to that value. Returns 0 on
2053 success, FSL_RC_MISUSE if !f or !pageName, FSL_RC_RANGE if
2054 !*pageName, and a host of other potential db-side errors
2055 indicating more serious problems. If no such page is found,
2056 newRid is not modified and this function returns 0 (as opposed
2057 to FSL_RC_NOT_FOUND) because that simplifies usage (so far).
2058
2059 On error *newRid is not modified.
2060
2061 @see fsl_wiki_load_latest()
2062 @see fsl_wiki_foreach_page()
2063 @see fsl_wiki_names_get()
2064 @see fsl_wiki_page_exists()
2065*/
2066FSL_EXPORT int fsl_wiki_latest_rid( fsl_cx * f, char const * pageName, fsl_id_t * newRid );
2067
2068/**
2069 Loads the artifact for the most recent version of the given wiki page,
2070 populating d with its contents.
2071
2072 Returns 0 on success. On error d might be partially populated,
2073 so it needs to be passed to fsl_deck_finalize() regardless of
2074 whether this function succeeds or fails.
2075
2076 Returns FSL_RC_NOT_FOUND if no page with that name is found.
2077
2078 @see fsl_wiki_latest_rid()
2079 @see fsl_wiki_names_get()
2080 @see fsl_wiki_page_exists()
2081*/
2082FSL_EXPORT int fsl_wiki_load_latest( fsl_cx * f, char const * pageName, fsl_deck * d );
2083
2084/**
2085 Returns true (non-0) if f's repo database contains a page with the
2086 given name, else false.
2087
2088 @see fsl_wiki_load_latest()
2089 @see fsl_wiki_latest_rid()
2090 @see fsl_wiki_names_get()
2091 @see fsl_wiki_names_get()
2092*/
2093FSL_EXPORT bool fsl_wiki_page_exists(fsl_cx * f, char const * pageName);
2094
2095/**
2096 A helper type for use with fsl_wiki_save(), intended primarily
2097 to help client-side code readability somewhat.
2098*/
2100/**
2101 Indicates that fsl_wiki_save() must only allow the creation of
2102 a new page, and must fail if such an entry already exists.
2103*/
2105/**
2106 Indicates that fsl_wiki_save() must only allow the update of an
2107 existing page, and will not create a branch new page.
2108*/
2110/**
2111 Indicates that fsl_wiki_save() must allow both the update and
2112 creation of pages. Trivia: "upsert" is a common SQL slang
2113 abbreviation for "update or insert."
2114*/
2116};
2117
2119
2120/**
2121 Saves wiki content to f's repository db.
2122
2123 pageName is the name of the page to update or create.
2124
2125 b contains the content for the page.
2126
2127 userName specifies the user name to apply to the change. If NULL
2128 or empty then fsl_cx_user_get() or fsl_user_name_guess() are
2129 used (in that order) to determine the name.
2130
2131 mimeType specifies the mime type for the content (may be NULL).
2132 Mime type names supported directly by fossil(1) include (as of
2133 this writing): text/x-fossil-wiki, text/x-markdown,
2134 text/plain
2135
2136 Whether or not this function is allowed to create a new page is
2137 determined by creationPolicy. If it is
2138 FSL_WIKI_SAVE_MODE_UPDATE, this function will fail with
2139 FSL_RC_NOT_FOUND if no page with the given name already exists.
2140 If it is FSL_WIKI_SAVE_MODE_CREATE and a previous version _does_
2141 exist, it fails with FSL_RC_ALREADY_EXISTS. If it is
2142 FSL_WIKI_SAVE_MODE_UPSERT then both the save-exiting and
2143 create-new cases are allowed. In summary:
2144
2145 - use FSL_WIKI_SAVE_MODE_UPDATE to allow updates to existing pages
2146 but disallow creation of new pages,
2147
2148 - use FSL_WIKI_SAVE_MODE_CREATE to allow creating of new pages
2149 but not of updating an existing page.
2150
2151 - FSL_WIKI_SAVE_MODE_UPSERT allows both updating and creating
2152 a new page on demand.
2153
2154 Returns 0 on success, or any number fsl_rc_e codes on error. On
2155 error no content changes are saved, and any transaction is
2156 rolled back or a rollback is scheduled if this function is
2157 called while a transaction is active.
2158
2159
2160 Potential TODO: add an optional (fsl_id_t*) output parameter
2161 which gets set to the new record's RID.
2162
2163 @see fsl_wiki_page_exists()
2164 @see fsl_wiki_names_get()
2165*/
2166FSL_EXPORT int fsl_wiki_save(fsl_cx * f, char const * pageName,
2167 fsl_buffer const * b, char const * userName,
2168 char const * mimeType, fsl_wiki_save_mode_t creationPolicy );
2169
2170/**
2171 Fetches the list of all wiki page names in f's current repo db
2172 and appends them as new (char *) strings to tgt. On error tgt
2173 might be partially populated (but this will only happen on an
2174 OOM or serious system-level error).
2175
2176 It is up to the caller free the entries added to the list. Some
2177 of the possibilities include:
2178
2179 ```
2180 fsl_list_visit( list, 0, fsl_list_v_fsl_free, NULL );
2181 fsl_list_reserve(list,0);
2182 // Or:
2183 fsl_list_clear(list, fsl_list_v_fsl_free, NULL);
2184 // Or simply:
2185 fsl_list_visit_free( list, 1 );
2186 ```
2187
2188*/
2190
2191/**
2192 F-cards each represent one file entry in a Manifest Artifact (i.e.,
2193 a checkin version).
2194
2195 All of the non-const pointers in this class are owned by the
2196 respective instance of the class OR by the fsl_deck which created
2197 it, and must neither be modified nor freed except via the
2198 appropriate APIs.
2199*/
2201 /**
2202 UUID of the underlying blob record for the file. NULL for
2203 removed entries.
2204 */
2206 /**
2207 Name of the file.
2208 */
2209 char * name;
2210 /**
2211 Previous name if the file was renamed, else NULL.
2212 */
2214 /**
2215 File permissions. Fossil only supports one "permission" per
2216 file, and it does not necessarily map to a real
2217 filesystem-level permission.
2218
2219 @see fsl_fileperm_e
2220 */
2222
2223 /**
2224 An internal optimization. Do not mess with this. When this is
2225 true, the various string members of this struct are not owned
2226 by this struct, but by the deck which created this struct. This
2227 is used when loading decks from storage - the strings are
2228 pointed to the original content data, rather than strdup()'d
2229 copies of it. fsl_card_F_clean() will DTRT and delete the
2230 strings (or not).
2231 */
2233};
2234/**
2235 Empty-initialized fsl_card_F structure, intended for use in
2236 initialization when embedding fsl_card_F in another struct or
2237 copy-initializing a const struct.
2238*/
2239#define fsl_card_F_empty_m { \
2240 NULL/*uuid*/, \
2241 NULL/*name*/, \
2242 NULL/*priorName*/, \
2243 0/*perm*/, \
2244 false/*deckOwnsStrings*/ \
2245}
2247
2248/**
2249 Represents a J card in a Ticket Control Artifact.
2250*/
2252 /**
2253 If true, the new value should be appended to any existing one
2254 with the same key, else it will replace any old one.
2255 */
2257 /**
2258 For internal use only.
2259 */
2260 unsigned char flags;
2261 /**
2262 The ticket field to update. The bytes are owned by this object.
2263 */
2264 char * field;
2265 /**
2266 The value for the field. The bytes are owned by this object.
2267 */
2268 char * value;
2269};
2270/** Empty-initialized fsl_card_J struct. */
2271#define fsl_card_J_empty_m {false,0,NULL, NULL}
2272/** Empty-initialized fsl_card_J struct. */
2274
2275/**
2276 Represents a tag in a Manifest or Control Artifact.
2277*/
2279 /**
2280 The type of tag.
2281 */
2283 /**
2284 UUID of the artifact this tag is tagging. When applying a tag to
2285 a new checkin, this value is left empty (=NULL) and gets replaced
2286 by a '*' in the resulting control artifact.
2287 */
2289 /**
2290 The tag's name. The bytes are owned by this object.
2291 */
2292 char * name;
2293 /**
2294 The tag's value. May be NULL/empty. The bytes are owned by
2295 this object.
2296 */
2297 char * value;
2298};
2299/** Defaults-initialized fsl_card_T instance. */
2300#define fsl_card_T_empty_m {FSL_TAGTYPE_INVALID, NULL, NULL,NULL}
2301/** Defaults-initialized fsl_card_T instance. */
2303
2304/**
2305 Types of cherrypick merges.
2306*/
2308/** Sentinel value. */
2310/** Indicates a cherrypick merge. */
2312/** Indicates a cherrypick backout. */
2314};
2316
2317/**
2318 Represents a Q card in a Manifest or Control Artifact.
2319*/
2321 /** 0==invalid, negative==backed out, positive=cherrypicked. */
2323 /**
2324 UUID of the target of the cherrypick. The bytes are owned by
2325 this object.
2326 */
2328 /**
2329 UUID of the baseline for the cherrypick. The bytes are owned by
2330 this object.
2331 */
2333};
2334/** Empty-initialized fsl_card_Q struct. */
2335#define fsl_card_Q_empty_m {FSL_CHERRYPICK_INVALID, NULL, NULL}
2336/** Empty-initialized fsl_card_Q struct. */
2338
2339/**
2340 Allocates a new J-card record instance
2341
2342 On success it returns a new record which must eventually be
2343 passed to fsl_card_J_free() to free its resources. On
2344 error (invalid arguments or allocation error) it returns NULL.
2345 field may not be NULL or empty but value may be either.
2346
2347 These records are immutable - the API provides no way to change
2348 them once they are instantiated.
2349*/
2351 char const * field,
2352 char const * value);
2353/**
2354 Frees a J-card record created by fsl_card_J_malloc().
2355 Is a no-op if cp is NULL.
2356*/
2358
2359/**
2360 Allocates a new fsl_card_T instance. If any of the pointer
2361 parameters are non-NULL, their values are assumed to be
2362 NUL-terminated strings, which this function copies. Returns NULL
2363 on allocation error. The returned value must eventually be passed
2364 to fsl_card_T_clean() or fsl_card_T_free() to free its resources.
2365
2366 If uuid is not NULL and fsl_is_uuid(uuid) returns false then
2367 this function returns NULL. If it is NULL and gets assigned
2368 later, it must conform to fsl_is_uuid()'s rules or downstream
2369 results are undefined.
2370
2371 @see fsl_card_T_free()
2372 @see fsl_card_T_clean()
2373 @see fsl_deck_T_add()
2374*/
2376 fsl_uuid_cstr uuid,
2377 char const * name,
2378 char const * value);
2379/**
2380 If t is not NULL, calls fsl_card_T_clean(t) and then passes t to
2381 fsl_free().
2382
2383 @see fsl_card_T_clean()
2384*/
2386
2387/**
2388 Frees up any memory owned by t and clears out t's state,
2389 but does not free t.
2390
2391 @see fsl_card_T_free()
2392*/
2394
2395/**
2396 Allocates a new cherrypick record instance. The type argument must
2397 be one of FSL_CHERRYPICK_ADD or FSL_CHERRYPICK_BACKOUT. target
2398 must be a valid UUID string. If baseline is not NULL then it also
2399 must be a valid UUID.
2400
2401 On success it returns a new record which must eventually be
2402 passed to fsl_card_Q_free() to free its resources. On
2403 error (invalid arguments or allocation error) it returns NULL.
2404
2405 These records are immutable - the API provides no way to change
2406 them once they are instantiated.
2407*/
2409 fsl_uuid_cstr target,
2410 fsl_uuid_cstr baseline);
2411/**
2412 Frees a cherrypick record created by fsl_card_Q_malloc().
2413 Is a no-op if cp is NULL.
2414*/
2416
2417/**
2418 Returns true (non-0) if f is not NULL and f has an opened repo
2419 which contains a checkin with the given rid, else it returns
2420 false.
2421
2422 As a special case, if rid==0 then this only returns true
2423 if the repository currently has no content in the blob
2424 table.
2425*/
2427
2428/**
2429 Fetches the list of all directory names for a given checkin record
2430 id or (if rid is negative) the whole repo over all of its combined
2431 history. Each name entry in the list is appended to tgt. The
2432 results are reduced to unique names only and are sorted
2433 lexically. If addSlash is true then each entry will include a
2434 trailing slash character, else it will not. The list does not
2435 include an entry for the top-most directory.
2436
2437 If rid is less than 0 then the directory list across _all_
2438 versions is returned. If it is 0 then the current checkout's RID
2439 is used (if a checkout is opened, otherwise a usage error is
2440 triggered). If it is positive then only directories for the
2441 given checkin RID are returned. If rid is specified, it is
2442 assumed to be the record ID of a commit (manifest) record, and
2443 it is impossible to distinguish between the results "invalid
2444 rid" and "empty directory list" (which is a legal result).
2445
2446 On success it returns 0 and tgt will have a number of (char *)
2447 entries appended to it equal to the number of subdirectories in
2448 the repo (possibly 0).
2449
2450 Returns non-0 on error, FSL_RC_MISUSE if !tgt, FSL_RC_NOT_A_REPO if
2451 f has no opened repository. On other errors error tgt might have
2452 been partially populated and the list contents should not be
2453 considered valid/complete. Results are undefined if f is NULL.
2454
2455 Ownership of the returned strings is transfered to the caller,
2456 who must eventually free each one using
2457 fsl_free(). fsl_list_visit_free() is the simplest way to free
2458 them all at once.
2459*/
2461 fsl_list * tgt, bool addSlash );
2462
2463
2464/**
2465 ZIPs up a copy of the contents of a specific version from f's
2466 opened repository db. sym is the symbolic name for the checkin
2467 to ZIP. filename is the name of the ZIP file to output the
2468 result to. See fsl_zip_writer for details and caveats of this
2469 library's ZIP creation. If vRootDir is not NULL and not empty
2470 then each file injected into the ZIP gets that directory
2471 prepended to its name.
2472
2473 If progressVisitor is not NULL then it is called once just before
2474 each file is processed, passed the F-card for the file about to be
2475 zipped and the progressState parameter. If it returns non-0,
2476 ZIPping is cancelled and that result code is returned. This is
2477 intended primarily for providing feedback on the zip progress, but
2478 could also be used to cancel the operation between files.
2479
2480 As of 2021-09-05 this routine automatically adds the files
2481 (manifest, manifest.uuid, manifest.tags) to the zip file,
2482 regardless of repository-level settings regarding those
2483 pseudo-files (see fsl_ckout_manifest_write()). As there are no
2484 F-cards associated with those non-files, the progressVisitor is not
2485 called for those.
2486
2487 BUG/FIXME: this function does not honor symlink content in a
2488 fossil-compatible fashion. If it encounters a symlink entry during
2489 ZIP generation, it will fail and f's error state will be updated
2490 with an explanation of this shortcoming.
2491
2492 @see fsl_zip_writer
2493 @see fsl_card_F_visitor_f()
2494*/
2496 char const * vRootDir,
2497 char const * fileName,
2498 fsl_card_F_visitor_f progressVisitor,
2499 void * progressState);
2500
2501
2502/**
2503 Callback state for use with fsl_repo_extract_f() implementations
2504 to stream a given version of a repository's file's, one file at a
2505 time, to a client. Instances are never created by client code,
2506 only by fsl_repo_extract() and its delegates, which pass them to
2507 client-provided fsl_repo_extract_f() functions.
2508*/
2510 /**
2511 The associated Fossil context.
2512 */
2514 /**
2515 RID of the checkin version for this file. For a given call to
2516 fsl_repo_extract(), this number will be the same across all
2517 calls to the callback function.
2518 */
2520 /**
2521 File-level blob.rid for fc. Can be used with, e.g.,
2522 fsl_mtime_of_manifest_file().
2523 */
2525 /**
2526 Client state passed to fsl_repo_extract(). Its interpretation
2527 is callback-implementation-dependent.
2528 */
2530 /**
2531 The F-card being iterated over. This holds the repo-level
2532 metadata associated with the file, other than its RID, which is
2533 available via this->fileRid.
2534
2535 Deleted files are NOT reported via the extraction process
2536 because reporting them accurately is trickier and more
2537 expensive than it could be. Thus this member's uuid field
2538 will always be non-NULL.
2539
2540 Certain operations which use this class, e.g. fsl_repo_ckout()
2541 and fsl_ckout_update(), will temporarily synthesize an F-card to
2542 represent the state of a file update, in which case this object's
2543 contents might not 100% reflect any given db-side state. e.g.
2544 fsl_ckout_update() synthesizes an F-card which reflects the
2545 current state of a file after applying an update operation to it.
2546 In such cases, the fCard->uuid may refer to a repository-side
2547 file even though the hash of the on-disk file contents may differ
2548 because of, e.g., a merge.
2549 */
2551
2552 /**
2553 If the fsl_repo_extract_opt object which was used to initiate the
2554 current extraction has the extractContent member set to false,
2555 this will be a NULL pointer. If it's true, this member points to
2556 a transient buffer which holds the full, undelta'd/uncompressed
2557 content of fc's file record. The content bytes are owned by
2558 fsl_repo_extract() and are invalidated as soon as this callback
2559 returns, so the callback must copy/consume them immediately if
2560 needed.
2561 */
2563
2564 /**
2565 These counters can be used by an extraction callback to calculate
2566 a progress percentage.
2567 */
2568 struct {
2569 /** The current file number, starting at 1. */
2570 uint32_t fileNumber;
2571 /** Total number of files to extract. */
2572 uint32_t fileCount;
2574};
2576
2577/**
2578 Initialized-with-defaults fsl_repo_extract_state instance, intended
2579 for const-copy initialization.
2580*/
2581#define fsl_repo_extract_state_empty_m {\
2582 NULL/*f*/, 0/*checkinRid*/, 0/*fileRid*/, \
2583 NULL/*state*/, NULL/*fCard*/, NULL/*content*/, \
2584 {/*count*/0,0} \
2585}
2586/**
2587 Initialized-with-defaults fsl_repo_extract_state instance,
2588 intended for non-const copy initialization.
2589*/
2591
2592/**
2593 A callback type for use with fsl_repo_extract(). See
2594 fsl_repo_extract_state for the meanings of xstate's various
2595 members. The xstate memory must be considered invalidated
2596 immediately after this function returns, thus implementations
2597 must copy or consume anything they need from xstate before
2598 returning.
2599
2600 Implementations must return 0 on success. As a special case, if
2601 FSL_RC_BREAK is returned then fsl_repo_extract() will stop
2602 looping over files but will report it as success (by returning
2603 0). Any other code causes extraction looping to stop and is
2604 returned as-is to the caller of fsl_repo_extract().
2605
2606 When returning an error, the client may use fsl_cx_err_set() to
2607 populate state->f with a useful error message which will
2608 propagate back up through the call stack.
2609
2610 @see fsl_repo_extract()
2611*/
2612typedef int (*fsl_repo_extract_f)( fsl_repo_extract_state const * xstate );
2613
2614/**
2615 Options for use with fsl_repo_extract().
2616*/
2618 /**
2619 The version of the repostitory to check out. This must be
2620 the blob.rid of a checkin artifact.
2621 */
2623 /**
2624 The callback to call for each extracted file in the checkin.
2625 May not be NULL.
2626 */
2628 /**
2629 Optional state pointer to pass to the callback when extracting.
2630 Its interpretation is client-dependent.
2631 */
2633 /**
2634 If true, the fsl_repo_extract_state::content pointer passed to
2635 the callback will be non-NULL and will contain the content of the
2636 file. If false, that pointer will be NULL. Such extraction is a
2637 relatively costly operation, so should only be enabled when
2638 necessary. Some uses cases can delay this decision until the
2639 callback and only fetch the content for cases which need it.
2640 */
2642};
2643
2645/**
2646 Initialized-with-defaults fsl_repo_extract_opt instance, intended
2647 for intializing via const-copy initialization.
2648*/
2649#define fsl_repo_extract_opt_empty_m \
2650 {0/*checkinRid*/,NULL/*callback*/, \
2651 NULL/*callbackState*/,false/*extractContent*/}
2652/**
2653 Initialized-with-defaults fsl_repo_extract_opt instance,
2654 intended for intializing new non-const instances.
2655*/
2657
2658/**
2659 Iterates over the file content of a single checkin in a repository,
2660 sending the appropriate version of each file's contents to a
2661 client-specified callback.
2662
2663 For each file in the given checkin, opt->callback() is passed a
2664 fsl_repo_extract_state instance containing enough information to,
2665 e.g., unpack the contents to a working directory, add it to a
2666 compressed archive, or send it to some other destination.
2667
2668 Returns 0 on success, non-0 on error. It will fail if f has no
2669 opened repository db.
2670
2671 If the callback returns any code other than 0 or FSL_RC_BREAK,
2672 looping over the list of files ends and this function returns
2673 that value. FSL_RC_BREAK causes looping to stop but 0 is
2674 returned.
2675
2676 See fsl_repo_extract_f() for more details about the semantics of
2677 the callback. See fsl_repo_extract_opt for the documentation of the
2678 various options.
2679
2680 Fossil's internal metadata format guarantees that files will be
2681 passed to the callback in "lexical order" (as defined by fossil's
2682 manifest format definition). i.e. the files will be passed in
2683 case-sensitive, alphabetical order. Note that upper-case letters
2684 sort before lower-case ones.
2685
2686 Sidebar: this function makes a bitwise copy of the 2nd argument
2687 before starting its work, just in case the caller gets the crazy
2688 idea to modify it from the extraction callback. Whether or not
2689 there are valid/interesting uses for such modification remains to
2690 be seen. If any are found, this copy behavior may change.
2691*/
2693 fsl_repo_extract_opt const * opt );
2694
2695/**
2696 Equivalent to fsl_tag_an_rid() except that it takes a symbolic
2697 artifact name in place of an artifact ID as the third
2698 argumemnt.
2699
2700 This function passes symToTag to fsl_sym_to_rid(), and on
2701 success passes the rest of the parameters as-is to
2702 fsl_tag_an_rid(). See that function the semantics of the other
2703 arguments and the return value, as well as a description of the
2704 side effects.
2705*/
2707 char const * symToTag, char const * tagName,
2708 char const * tagValue, char const * userName,
2709 double mtime, fsl_id_t * newId );
2710
2711/**
2712 Adds a control record to f's repositoriy that either creates or
2713 cancels a tag.
2714
2715 artifactRidToTag is the RID of the record to be tagged.
2716
2717 tagType is the type (add, cancel, or propagate) of tag.
2718
2719 tagName is the name of the tag. Must not be NULL/empty.
2720
2721 tagValue is the optional value for the tag. May be NULL.
2722
2723 userName is the user's name to apply to the artifact. May not be
2724 empty/NULL. Use fsl_user_name_guess() to try to figure out a
2725 proper user name based on the environment. See also:
2726 fsl_cx_user_get(), but note that the application must first
2727 use fsl_cx_user_set() to set a context's user name.
2728
2729 mtime is the Julian Day timestamp for the new artifact. Pass a
2730 value <=0 to use the current time.
2731
2732 If newId is not NULL then on success the rid of the new tag control
2733 artifact is assigned to *newId.
2734
2735 Returns 0 on success and has about a million and thirteen
2736 possible error conditions. On success a new artifact record is
2737 written to the db, its RID being written into newId as described
2738 above.
2739
2740 If the artifact being tagged is private, the new tag is also
2741 marked as private.
2742
2743*/
2745 fsl_id_t artifactRidToTag, char const * tagName,
2746 char const * tagValue, char const * userName,
2747 double mtime, fsl_id_t * newId );
2748
2749/**
2750 Searches for a repo.tag entry given name in the given context's
2751 repository db. If found, it returns the record's id. If no
2752 record is found and create is true (non-0) then a tag is created
2753 and its entry id is returned. Returns 0 if it finds no entry, a
2754 negative value on error. On db-level error, f's error state is
2755 updated.
2756*/
2757FSL_EXPORT fsl_id_t fsl_tag_id( fsl_cx * f, char const * tag, bool create );
2758
2759
2760/**
2761 Returns true if the checkin with the given rid is a leaf, false if
2762 not. Returns false if f has no repo db opened, the query fails
2763 (likely indicating that it is not a repository db), or just about
2764 any other conceivable non-success case.
2765
2766 A leaf, by the way, is a commit which has no children in the same
2767 branch.
2768
2769 Sidebar: this function calculates whether the RID is a leaf, as
2770 opposed to checking the "static" (pre-calculated) list of leaves in
2771 the [leaf] table.
2772*/
2774/**
2775 Returns true if, according to f's current repo's [event] table,
2776 rid refers to a checkin, else false.
2777*/
2779
2780/**
2781 Counts the number of primary non-branch children for the given
2782 check-in.
2783
2784 A primary child is one where the parent is the primary parent, not
2785 a merge parent. A "leaf" is a node that has zero children of any
2786 kind. This routine counts only primary children.
2787
2788 A non-branch child is one which is on the same branch as the parent.
2789
2790 Returns a negative value on error.
2791*/
2793 fsl_id_t rid);
2794
2795/**
2796 Looks for the delta table record where rid==deltaRid, and
2797 returns that record's srcid via *rv. Returns 0 on success, non-0
2798 on error. If no record is found, *rv is set to 0 and 0 is
2799 returned (as opposed to FSL_RC_NOT_FOUND) because that generally
2800 simplifies the error checking.
2801
2802 Results are undefined if any pointer argument is NULL.
2803*/
2805 fsl_id_t * rv );
2806/* Deprecated name for fsl_delta_r2s. */
2807#define fsl_delta_src_id fsl_delta_r2s
2808
2809/**
2810 The counterpart of fsl_delta_r2s(): for a given delta.srcid, return
2811 the associated delta.rid via *rv. See that function for more
2812 details.
2813*/
2815 fsl_id_t * rv );
2816
2817
2818/**
2819 Return true if the given artifact ID should is listed in f's
2820 shun table or if zUuid is an SHA1 has and f's hash policy
2821 is set to FSL_HPOLICY_SHUN_SHA1.
2822
2823 This function has no way to report errors except via the f
2824 object. If there is an error in this call, f's error state will be
2825 updated.
2826
2827 Reminder to self: there is no fsl_is_shunned_rid() because rids
2828 refer to blob table records and the blob table is not supposed to
2829 contain shunned artifacts.
2830*/
2832/* Old name for fsl_is_shunned_uuid(). */
2833#define fsl_uuid_is_shunned fsl_is_shunned_uuid
2834
2835
2836/**
2837 Compute the "mtime" of the file given whose blob.rid is "fid"
2838 that is part of check-in "vid". The mtime will be the mtime on
2839 vid or some ancestor of vid where fid first appears. Note that
2840 fossil does not track the "real" mtimes of files, it only
2841 computes reasonable estimates for those files based on the
2842 timestamps of their most recent checkin in the ancestry of vid.
2843
2844 If fid is 0 or less then the D-card time of the artifact with the
2845 blob.rid == vid is written to pMTime (this is a much less expensive
2846 operation, by the way). In this particular case (A) vid may refer
2847 to any artifact type which has a D-card and (B) FSL_RC_NOT_FOUND is
2848 returned if vid is not a valid artifact RID.
2849
2850 On success, if pMTime is not null then the result is written to
2851 *pMTime.
2852
2853 Returns 0 on success, non-0 on error. Returns FSL_RC_NOT_FOUND
2854 if fid is not found in vid.
2855
2856 This routine is much more efficient if used to answer several
2857 queries in a row for the same manifest (the vid parameter). It
2858 is least efficient when it is passed intermixed manifest IDs,
2859 e.g. (1, 3, 1, 4, 1,...). This is a side-effect of the caching
2860 used in the computation of ancestors for a given vid.
2861*/
2863 fsl_time_t * pMTime);
2864
2865/**
2866 A convenience form of fsl_mtime_of_manifest_file() which looks up
2867 fc's RID based on its UUID. vid must be the RID of the checkin
2868 version fc originates from. See fsl_mtime_of_manifest_file() for
2869 full details - this function simply calculates the 3rd argument
2870 for that one.
2871*/
2873 fsl_time_t * pMTime);
2874
2875/**
2876 Ensures that the given list has capacity for at least n entries. If
2877 the capacity is currently equal to or less than n, this is a no-op
2878 unless n is 0, in which case li->list is freed and the list is
2879 zeroed out. Else li->list is expanded to hold at least n
2880 elements. Returns 0 on success, FSL_RC_OOM on allocation error.
2881 */
2883
2884/**
2885 Frees all memory owned by li and the F-cards it contains. Does not
2886 free the li pointer.
2887*/
2889
2890/**
2891 Iterates over all artifacts in f's current repository of the given
2892 type, passing each one to the given callback. If the callback
2893 returns non-0, iteration stops and that code is propagated back to
2894 the caller _unless_ the code is FSL_RC_BREAK, which means to stop
2895 iteration and return 0.
2896
2897 The following artifact types are currently supported by this
2898 operation:
2899
2900 FSL_SATYPE_CHECKIN, FSL_SATYPE_CONTROL, FSL_SATYPE_WIKI,
2901 FSL_SATYPE_TICKET, FSL_SATYPE_TECHNOTE, FSL_SATYPE_FORUMPOST
2902
2903 (CLUSTER and ATTACHMENT are missing only because they're not(?)
2904 readily findable without parsing every blob in the blob
2905 table.)
2906
2907 The decks are iterated over an an unspecified order except for:
2908
2909 - WIKI and TECHNOTE entries are visited from newest to oldest.
2910
2911 - TICKET entries are visited from oldest to newest to accommodate
2912 reconstructing their aggregate state in the callback.
2913
2914 Each deck is finalized immediately after the callback returns, so
2915 the callback must not hold any pointers to the deck or its
2916 contents.
2917
2918 Returns 0 on success or any number of error codes from lower levels,
2919 including, but not limited to:
2920
2921 - FSL_RC_OOM on allocation error
2922 - FSL_RC_NOT_A_REPO if f has no repository opened.
2923 - FSL_RC_TYPE if the 2nd argument is invalid or if its type is
2924 not supported (e.g. FSL_SATYPE_CLUSTER).
2925 - FSL_RC_MISUSE if the 3rd argument is NULL.
2926
2927*/
2929 fsl_deck_visitor_f visitor,
2930 void * visitorState);
2931
2932/**
2933 Holds options for use with fsl_branch_create().
2934*/
2936 /**
2937 The checkin RID from which the branch should originate.
2938 */
2940 /**
2941 The name of the branch. May not be NULL or empty.
2942 */
2943 char const * name;
2944 /**
2945 User name for the branch. If NULL, fsl_cx_user_get() will
2946 be used.
2947 */
2948 char const * user;
2949 /**
2950 Optional comment (may be NULL). If NULL or empty, a default
2951 comment is generated (because fossil requires a non-empty
2952 comment string).
2953 */
2954 char const * comment;
2955 /**
2956 Optional background color for the fossil(1) HTML timeline
2957 view. Must be in \#RRGGBB format, but this API does not
2958 validate it as such.
2959 */
2960 char const * bgColor;
2961 /**
2962 The julian time of the branch. If 0 or less, default is the
2963 current time.
2964 */
2965 double mtime;
2966 /**
2967 If true, the branch will be marked as private.
2968 */
2970};
2972#define fsl_branch_opt_empty_m { \
2973 0/*basisRid*/, NULL/*name*/, \
2974 NULL/*user*/, NULL/*comment*/, \
2975 NULL/*bgColor*/, \
2976 0.0/*mtime*/, 0/*isPrivate*/ \
2977 }
2979
2980/**
2981 Creates a new branch in f's repository. The 2nd paramter holds
2982 the options describing the branch. The 3rd parameter may be
2983 NULL, but if it is not then on success the RID of the new
2984 manifest is assigned to *newRid.
2985
2986 In Fossil branches are implemented as tags. The branch name
2987 provided by the client will cause the creation of a tag with
2988 name name plus a "sym-" prefix to be created (if needed).
2989 "sym-" denotes that it is a "symbolic tag" (fossil's term for
2990 "symbolic name applying to one or more checkins,"
2991 i.e. branches).
2992
2993 Creating a branch cancels all other branch tags which the new
2994 branch would normally inherit.
2995
2996 Returns 0 on success, non-0 on error.
2997*/
2999
3000/**
3001 Checks f's repo db for a setting named 'main-branch'. If
3002 found. *zOut is set to that string. The mememory is owned by f and
3003 is retained for later calls to this function, but it may be
3004 invalidated by certain fsl APIs (namely this very function, if
3005 forceReload is true, and fsl_cx_finalize()). If forceReload is true
3006 then any cached value is freed and re-loaded.
3007
3008 Returns 0 on success. On error, *zOut is not modified. If no such
3009 setting is found, "trunk" is used.
3010 */
3011FSL_EXPORT int fsl_branch_main(fsl_cx *f, char const **zOut, bool forceReload);
3012
3013/**
3014 Tries to determine the [filename.fnid] value for the given
3015 filename. Returns a positive value if it finds one, 0 if it
3016 finds none, and some unspecified negative value(s) for any sort
3017 of error. filename must be a normalized, relative filename (as it
3018 is recorded by a repo).
3019*/
3020FSL_EXPORT fsl_id_t fsl_repo_filename_fnid( fsl_cx * f, char const * filename );
3021
3022/**
3023 Resolves client-provided symbol as an artifact's db record ID.
3024 f must have an opened repository db, and some symbols can only
3025 be looked up if it has an opened checkout (see the list below).
3026
3027 Returns 0 and sets *rv to the id if it finds an unambiguous
3028 match.
3029
3030 Returns FSL_RC_MISUSE if !sym, !*sym, or !rv.
3031
3032 Returns FSL_RC_NOT_A_REPO if f has no opened repository.
3033
3034 Returns FSL_RC_AMBIGUOUS if sym is a partial UUID which matches
3035 multiple full UUIDs.
3036
3037 Returns FSL_RC_NOT_FOUND if it cannot find anything.
3038
3039 Symbols supported by this function:
3040
3041 - SHA1/3 hash
3042 - SHA1/3 hash prefix of at least 4 characters
3043 - Symbolic Name, e.g. branch name
3044 - "tag:" + symbolic name
3045 - Date or date-time
3046 - "date:" + Date or date-time
3047 - symbolic-name ":" date-time
3048 - "tip" means the most recent checkin, regardless of its branch
3049 - "rid:###" resolves to the hash of blob.rid ### if that RID is in
3050 the database
3051
3052 The following additional forms are available in local checkouts:
3053
3054 - "current"
3055 - "prev" or "previous"
3056 - "next"
3057
3058 The following prefix may be applied to the above to modify how
3059 they are resolved:
3060
3061 - "root:" prefix resolves to the checkin of the parent branch from
3062 which the record's branch divered. i.e. the version from which it
3063 was branched. In the trunk this will always resolve to the first
3064 checkin.
3065
3066 - "start:" prefix resolves to the first checkin of the branch to
3067 which the given checkin belongs. This differs from "root:" by a
3068 single checkin: the "root:" point is the parent checkin of the
3069 "start:" point.
3070
3071 - "merge-in:" TODO - document this once its implications are
3072 understood.
3073
3074 If type is not FSL_SATYPE_ANY then it will only match artifacts of
3075 the specified type. In order to resolve arbitrary UUIDs, e.g.
3076 those of arbitrary blob content, type needs to be FSL_SATYPE_ANY.
3077*/
3078FSL_EXPORT int fsl_sym_to_rid( fsl_cx * f, char const * sym,
3079 fsl_satype_e type, fsl_id_t * rv );
3080
3081/**
3082 Similar to fsl_sym_to_rid() but on success it returns a UUID string
3083 by assigning it to *rv (if rv is not NULL). If rid is not NULL then
3084 on success the db record ID corresponding to the returned UUID is
3085 assigned to *rid. The caller must eventually free the returned
3086 string memory by passing it to fsl_free(). Returns 0 if it finds a
3087 match and one of any number of possible result codes on error, most
3088 notably FSL_RC_NOT_FOUND if no match is found.
3089*/
3090FSL_EXPORT int fsl_sym_to_uuid( fsl_cx * f, char const * sym,
3091 fsl_satype_e type, fsl_uuid_str * rv,
3092 fsl_id_t * rid );
3093
3094
3095/**
3096 Searches f's repo database for the a blob with the given uuid
3097 (any unique UUID prefix). On success a positive record ID is
3098 returned. On error one of several unspecified negative values is
3099 returned. If no uuid match is found 0 is returned.
3100
3101 Error cases include: either argument is NULL, uuid does not appear
3102 to be a full or partial UUID (or is too long), uuid is ambiguous
3103 (try providing a longer one). For error cases other than an invalid
3104 2nd argument, f's error state is updated.
3105
3106 This implementation is more efficient when given a full, valid UUID
3107 (one for which fsl_is_uuid() returns true).
3108*/
3109FSL_EXPORT fsl_id_t fsl_uuid_to_rid( fsl_cx * f, char const * uuid );
3110
3111/**
3112 The opposite of fsl_uuid_to_rid(), this returns the UUID string
3113 of the given blob record ID. Ownership of the string is passed
3114 to the caller and it must eventually be freed using
3115 fsl_free(). Returns NULL on error (invalid arguments or f has no
3116 repo opened) or if no blob record is found. If no record is
3117 found, f's error state is updated with an explanation of the
3118 problem.
3119*/
3121
3122/**
3123 Works like fsl_rid_to_uuid() but assigns the UUID to the given
3124 buffer, re-using its memory, if any. Returns 0 on success,
3125 FSL_RC_MISUSE if rid is not positive, FSL_RC_OOM on allocation
3126 error, and FSL_RC_NOT_FOUND if no blob entry matching the given rid
3127 is found.
3128*/
3130
3131/**
3132 This works identically to fsl_rid_to_uuid() except that it will
3133 only resolve to a UUID if an artifact matching the given type has
3134 that UUID. If no entry is found, f's error state gets updated
3135 with a description of the problem.
3136
3137 This can be used to distinguish artifact UUIDs from file blob
3138 content UUIDs by passing the type FSL_SATYPE_ANY. A non-artifact
3139 blob will return NULL in that case, but any artifact type will
3140 match (assuming rid is valid).
3141*/
3143 fsl_satype_e type);
3144/**
3145 Returns the raw SQL code for a Fossil global config database.
3146
3147 TODO: add optional (fsl_size_t*) to return the length.
3148*/
3150
3151/**
3152 Returns the raw SQL code for the "static" parts of a Fossil
3153 repository database. These are the parts which are immutable
3154 (for the most part) between Fossil versions. They change _very_
3155 rarely.
3156
3157 TODO: add optional (fsl_size_t*) to return the length.
3158*/
3159FSL_EXPORT char const * fsl_schema_repo1(void);
3160
3161/**
3162 Returns the raw SQL code for the "transient" parts of a Fossil
3163 repository database - any parts which can be calculated via data
3164 held in the primary "static" schemas. These parts are
3165 occassionally recreated, e.g. via a 'rebuild' of a repository.
3166
3167 TODO: add optional (fsl_size_t*) to return the length.
3168*/
3169FSL_EXPORT char const * fsl_schema_repo2(void);
3170
3171/**
3172 Returns the raw SQL code for a Fossil checkout database.
3173
3174 TODO: add optional (fsl_size_t*) to return the length.
3175*/
3176FSL_EXPORT char const * fsl_schema_ckout(void);
3177
3178/**
3179 Returns the raw SQL code for a Fossil checkout db's
3180 _default_ core ticket-related tables.
3181
3182 TODO: add optional (fsl_size_t*) to return the length.
3183
3184 @see fsl_cx_schema_ticket()
3185*/
3187
3188/**
3189 Returns the raw SQL code for the "forum" parts of a Fossil
3190 repository database.
3191
3192 TODO: add optional (fsl_size_t*) to return the length.
3193*/
3194FSL_EXPORT char const * fsl_schema_forum(void);
3195
3196/**
3197 If f's opened repository has a non-empty config entry named
3198 'ticket-table', this returns its text via appending it to
3199 pOut. If no entry is found, fsl_schema_ticket() is appended to
3200 pOut.
3201
3202 Returns 0 on success. On error the contents of pOut must not be
3203 considered valid but pOut might be partially populated.
3204*/
3206
3207/**
3208 Returns the raw SQL code for Fossil ticket reports schemas.
3209 This gets installed as needed into repository databases.
3210
3211 TODO: add optional (fsl_size_t*) to return the length.
3212*/
3214
3215/**
3216 This is a wrapper around fsl_cx_hash_buffer() which looks for a
3217 matching artifact for the given input blob. It first hashes src
3218 using f's "alternate" hash and then, if no match is found, tries
3219 again with f's preferred hash.
3220
3221 On success (a match is found):
3222
3223 - Returns 0.
3224
3225 - If ridOut is not NULL, *ridOut is set to the RID of the matching
3226 blob.
3227
3228 - If hashOut is not NULL, *hashOut is set to the hash of the
3229 blob. Its ownership is transferred to the caller, who must
3230 eventually pass it to fsl_free().
3231
3232 If no matching blob is found in the repository, FSL_RC_NOT_FOUND is
3233 returned (but f's error state is not annotated with more
3234 information). Returns FSL_RC_NOT_A_REPO if f has no repository
3235 opened. For more serious errors, e.g. allocation error or db
3236 problems, another (more serious) result code is returned,
3237 e.g. FSL_RC_OOM or FSL_RC_DB.
3238
3239 If FSL_RC_NOT_FOUND is returned and hashOut is not NULL, *hashOut
3240 is set to the value of f's preferred hash and *hashOut's ownership
3241 is transferred to the caller. *ridOut is only modified if 0 is
3242 returned, in which case *ridOut will have a positive value.
3243*/
3245 fsl_id_t * ridOut,
3246 fsl_uuid_str * hashOut );
3247
3248/**
3249 Returns true if the specified file name ends with any reserved
3250 name, e.g.: _FOSSIL_ or .fslckout.
3251
3252 For the sake of efficiency, zFilename must be a canonical name,
3253 e.g. an absolute or checkout-relative path using only forward slash
3254 ('/') as a directory separator.
3255
3256 On Windows builds, this also checks for reserved Windows filenames,
3257 e.g. "CON" and "PRN".
3258
3259 nameLen must be the length of zFilename. If it is negative,
3260 fsl_strlen() is used to calculate it.
3261*/
3262FSL_EXPORT bool fsl_is_reserved_fn(const char *zFilename,
3263 fsl_int_t nameLen );
3264
3265/**
3266 Uses fsl_is_reserved_fn() to determine whether the filename part of
3267 zPath is legal for use as an in-repository filename. If it is, 0 is
3268 returned, else FSL_RC_RANGE (or FSL_RC_OOM) is returned and f's
3269 error state is updated to indicate the nature of the problem. nFile
3270 is the length of zPath. If negative, fsl_strlen() is used to
3271 determine its length.
3272
3273 If relativeToCwd is true then zPath, if not absolute, is
3274 canonicalized as if were relative to the current working directory
3275 (see fsl_getcwd()), else it is assumed to be relative to the
3276 current checkout (if any - falling back to the current working
3277 directory). This flag is only relevant if zPath is not absolute and
3278 if f has a checkout opened. An absolute zPath is used as-is and if
3279 no checkout is opened then relativeToCwd is always treated as if it
3280 were true.
3281
3282 This routine does not validate that zPath lives inside a checkout
3283 nor that the file actually exists. It does only name comparison and
3284 only uses the filesystem for purposes of canonicalizing (if needed)
3285 zPath.
3286
3287 This routine does not require that f have an opened repo, but if it
3288 does then this routine compares the canonicalized forms of both the
3289 repository db and the given path and fails if zPath refers to the
3290 repository db. Be aware that the relativeToCwd flag may influence
3291 that test.
3292
3293 This routine also checks fsl_ckout_manifest_setting() and reports
3294 any of the files represented by that function's results as being
3295 reserved. It only treats such names as reserved if they are at the
3296 top level of the repository - those same names in subdirectories are
3297 not reserved. If f has no checkout opened and relativeToCwd is true
3298 then those names are considered to be at the "top" if they are in
3299 the current directory.
3300*/
3301FSL_EXPORT int fsl_reserved_fn_check(fsl_cx * f, const char *zPath,
3302 fsl_int_t nFile, bool relativeToCwd);
3303
3304/**
3305 Recompute/rebuild the entire repo.leaf table. This is not normally
3306 needed, as leaf tracking is part of the crosslinking process, but
3307 "just in case," here it is.
3308
3309 This can supposedly be expensive (in time) for a really large
3310 repository. Testing implies otherwise.
3311
3312 Returns 0 on success. On error f's error state may be updated.
3313 Results are undefined if f is invalid or has no opened repository.
3314*/
3316
3317/**
3318 Flags for use with fsl_leaves_compute().
3319*/
3321/**
3322 Compute all leaves regardless of the "closed" tag.
3323*/
3325/**
3326 Compute only leaves without the "closed" tag.
3327*/
3329/**
3330 Compute only leaves with the "closed" tag.
3331*/
3333};
3335
3336/**
3337 Creates a temporary table named "leaves" if it does not already
3338 exist, else empties it. Populates that table with the RID of all
3339 check-ins that are leaves which are descended from the checkin
3340 referred to by vid.
3341
3342 A "leaf" is a check-in that has no children in the same branch.
3343 There is a separate permanent table named [leaf] that contains all
3344 leaves in the tree. This routine is used to compute a subset of
3345 that table consisting of leaves that are descended from a single
3346 check-in.
3347
3348 The leafMode flag determines behavior associated with the "closed"
3349 tag, as documented for the fsl_leaves_compute_e enum.
3350
3351 If vid is <=0 then this function, after setting up or cleaning out
3352 the [leaves] table, simply copies the list of leaves from the
3353 repository's pre-computed [leaf] table (see
3354 fsl_repo_leaves_rebuild()).
3355
3356 @see fsl_leaves_computed_has()
3357 @see fsl_leaves_computed_count()
3358 @see fsl_leaves_computed_latest()
3359 @see fsl_leaves_computed_cleanup()
3360*/
3362 fsl_leaves_compute_e leafMode);
3363
3364/**
3365 Requires that a prior call to fsl_leaves_compute() has succeeded,
3366 else results are undefined.
3367
3368 Returns true if the leaves list computed by fsl_leaves_compute() is
3369 not empty, else false. This is more efficient than checking
3370 against fsl_leaves_computed_count()>0.
3371*/
3373
3374/**
3375 Requires that a prior call to fsl_leaves_compute() has succeeded,
3376 else results are undefined.
3377
3378 Returns a count of the leaves list computed by
3379 fsl_leaves_compute(), or a negative value if a db-level error is
3380 encountered. On errors other than FSL_RC_OOM, f's error state will
3381 be updated with information about the error.
3382*/
3384
3385/**
3386 Requires that a prior call to fsl_leaves_compute() has succeeded,
3387 else results are undefined.
3388
3389 Returns the RID of the most recent checkin from those computed by
3390 fsl_leaves_compute(), 0 if no entries are found, or a negative
3391 value if a db-level error is encountered. On errors other than
3392 FSL_RC_OOM, f's error state will be updated with information about
3393 the error.
3394*/
3396
3397/**
3398 Cleans up any db-side resources created by fsl_leaves_compute().
3399 e.g. drops the temporary table created by that routine. Any errors
3400 are silenty ignored.
3401*/
3403
3404/**
3405 Returns true if f's current repository has the
3406 forbid-delta-manifests setting set to a truthy value. Results are
3407 undefined if f has no opened repository. Some routines behave
3408 differently if this setting is enabled. e.g. fsl_checkin_commit()
3409 will never generate a delta manifest and fsl_deck_save() will
3410 refuse to save a delta. This does not affect parsing or deltas or
3411 those which are injected into the db via lower-level means (e.g. a
3412 direct blob import or from a remote sync).
3413
3414 Results are undefined if f has no opened repository.
3415*/
3417
3418/**
3419 This is a variant of fsl_ckout_manifest_write() which writes data
3420 regarding the given manifest RID to the given blobs. If manifestRid
3421 is 0 or less then the current checkout is assumed and
3422 FSL_RC_NOT_A_CKOUT is returned if no checkout is opened (or
3423 FSL_RC_RANGE if an empty checkout is opened - a freshly-created
3424 repository with no checkins).
3425
3426 For each buffer argument which is not NULL, the corresponding
3427 checkin-related data are appended to it. All such blobs will end
3428 in a terminating newline character.
3429
3430 Returns 0 on success, any of numerious non-0 fsl_rc_e codes on
3431 error.
3432*/
3434 fsl_id_t manifestRid,
3435 fsl_buffer * manifest,
3436 fsl_buffer * manifestUuid,
3437 fsl_buffer * manifestTags );
3438
3439
3440/**
3441 "Stage" flag for use with fsl_annotate_step and
3442 fsl_annotate_step_f().
3443*/
3445/**
3446 Indicates that the current fsl_annotate_step_f() call is
3447 part of the "version dump" stage of the annotation.
3448*/
3450/**
3451 Indicates that the current fsl_annotate_step_f() call has
3452 complete version information for the line it is reporting
3453 about.
3454*/
3456/**
3457 Indicates that the current fsl_annotate_step_f() call has
3458 only partial version information for the line it is reporting
3459 about, as a result of a limited-run annotation.
3460*/
3462};
3464
3465/**
3466 Callback state for use by fsl_annotate_step_f().
3467
3468 ACHTUNG: this state gets repopulated for each call to the
3469 fsl_annote_step_f() callback and any pointers it holds must be
3470 treated as if they are invalidated as soon as the callback returns
3471 (whether or not that is the case is undefined, though).
3472
3473 Not all state is set on each call involving this object. See the
3474 stepType member for details.
3475*/
3477 /**
3478 Tells the caller the "type" of annotation step this call
3479 represents. The type of step will determine which fields
3480 of this object are populated when it is passed to a
3481 fsl_annotate_step_f() callback:
3482
3483 Always set:
3484
3485 stepType, stepNumber (but interpretation varies - see that
3486 member's docs for details).
3487
3488 FSL_ANNOTATE_STEP_VERSION: fileHash, versionHash, mtime
3489
3490 FSL_ANNOTATE_STEP_LIMITED: stepNumber (always 0 for the limited
3491 case), lineNumber, line, lineNength.
3492
3493 FSL_ANNOTATE_STEP_FULL: as for FSL_ANNOTATE_STEP_LIMITED plus:
3494 fileHash, versionHash, mtime, username.
3495 */
3497 /**
3498 Step number in this annotation run. When this->stepType is
3499 FSL_ANNOTATE_STEP_VERSION, this value is the relative number of
3500 the version, starting at 0 and incremented by 1 on each call. In
3501 the other modes it is 0-based relative version from which the
3502 current line is from, or negative if that information is
3503 incomplete due to a limited annotation run. e.g. a value of 3
3504 indicates that this line is from 3 version away from the starting
3505 version.
3506 */
3508 /**
3509 Line number for the current file.
3510 */
3511 uint32_t lineNumber;
3512 /**
3513 NUL-terminated current line of the input file, minus any
3514 newline and/or carriage return.
3515 */
3516 char const * line;
3517 /**
3518 The number of bytes in this->line.
3519 */
3520 uint32_t lineLength;
3521 /**
3522 The hash of the file version from which this->line was
3523 pulled.
3524 */
3526 /**
3527 The hash of the checkin version from which this->line was
3528 pulled.
3529 */
3531
3532 /**
3533 The mtime field from the [event] table (timeline) entry
3534 associated with this version. This is a Julian Date and, because
3535 it is updated by annotations which modify timestamps in the
3536 [event] table, it reflects any "edited" time (if any).
3537
3538 @see fsl_julian_to_iso8601()
3539 */
3540 double mtime;
3541 /**
3542 The user name this change was attributed to, noting that merges
3543 are attributed to the one who did the merge.
3544 */
3545 char const * username;
3546};
3547
3548/** Convenience typedef. */
3550/** Forward decl and convenience typedef. */
3552
3553/**
3554 Callback for use with fsl_annotate(). Implementations receive
3555 state about each step of an annotation process. They must return 0
3556 on success. On error, their non-0 result code is propagated back
3557 to the fsl_annotate() caller.
3558*/
3559typedef int (*fsl_annotate_step_f)(void * state,
3560 fsl_annotate_opt const * opt,
3561 fsl_annotate_step const * step);
3562
3563/**
3564 A fsl_annotate_step_f() impl. which requires that its first argument
3565 be a fsl_outputer. It formats each step of the annotation
3566 in a manner similar to fossil(1) and forwards the result to
3567 state->out(state->state, ...), returning that function's result code.
3568*/
3570 fsl_annotate_opt const * opt,
3571 fsl_annotate_step const * step);
3572
3573/**
3574 Configuration for use with fsl_annotate().
3575
3576 This structure holds options for the "annotate" operation and its
3577 close cousin, "blame" a.k.a. "praise." Annotation takes a given
3578 file version and builds a line-by-line history, showing when each
3579 line was last modified. The "blame" a.k.a. "praise" option includes
3580 *who* modified that line.
3581*/
3583 /**
3584 The repository-root-relative NUL-terminated filename to annotate.
3585 */
3586 char const * filename;
3587 /**
3588 The checkin from which the file's version should be selected. A
3589 value of 0 or less means the current checkout, if in a checkout,
3590 and is otherwise an error.
3591 */
3593 /**
3594 The origin checkin version. A value of 0 or less means the "root of the
3595 tree."
3596
3597 TODO: figure out and explain the difference between versionRid
3598 and originRid.
3599 */
3601 /**
3602 The maximum number of versions to search through.
3603 */
3605
3606 /**
3607 An approximate number of milliseconds of processing time to limit
3608 the annotation to. Note that this is measured in CPU time, not
3609 "wall clock" time. This value is rough minimum approximation,
3610 and the annotation will stop at the first processing step after which
3611 this limit has been hit or surpassed.
3612
3613 Even with this limit in place, the annotation engine may impose a
3614 minimum number of versions to step through before it enforces
3615 this limit.
3616
3617 If both this and limitVersions are set to positive values, the
3618 first limit which is exceeded is applied.
3619 */
3620 uint32_t limitMs;
3621 /**
3622 - 0 = do not ignore any spaces.
3623 - <0 = ignore trailing end-of-line spaces.
3624 - >1 = ignore all spaces
3625 */
3627 /**
3628 If true, include the name of the user for which each change is
3629 attributed (noting that merges show whoever merged the change,
3630 which may differ from the original committer, and amended user
3631 names will be used over those in the initial commit). If false,
3632 show only version information.
3633
3634 This option is alternately known as "blame".
3635
3636 For reasons lost to history, blame/praise mode does not include
3637 line numbers. That may change in the future.
3638 */
3640 /**
3641 Output file blob versions, instead of checkin versions.
3642 */
3644
3645 /**
3646 If true, annotation output will start with a list of all
3647 versions analyzed by the annotation process.
3648 */
3650 /**
3651 The output channel for the resulting annotation.
3652 */
3654 /**
3655 State for passing as the first argument to this->out().
3656 */
3657 void * outState;
3658};
3659
3660/** Initialized-with-defaults fsl_annotate_opt structure, intended for
3661 const-copy initialization. */
3662#define fsl_annotate_opt_empty_m {\
3663 NULL/*filename*/, \
3664 0/*versionRid*/,0/*originRid*/, \
3665 0U/*limitVersions*/, 0U/*limitMs*/,\
3666 0/*spacePolicy*/, \
3667 false/*praise*/, false/*fileVersions*/, \
3668 false/*dumpVersions*/, \
3669 NULL/*out*/, NULL/*outState*/ \
3670}
3671
3672/** Initialized-with-defaults fsl_annotate_opt structure, intended for
3673 non-const copy initialization. */
3675
3676/**
3677 UNDER CONSTRUCTION. Not yet known to be fully functional or
3678 bug-free.
3679
3680 Runs an "annotation" of an SCM-controled file and sends the results
3681 to opt->out().
3682
3683 Returns 0 on success. On error, returns one of:
3684
3685 - FSL_RC_OOM on OOM
3686
3687 - FSL_RC_NOT_A_CKOUT if opt->versionRid<=0 and f has no opened checkout.
3688
3689 - FSL_RC_NOT_FOUND if the given filename cannot be found in the
3690 repository OR a given version ID does not resolve to a blob. (Sorry
3691 about this ambiguity!)
3692
3693 - FSL_RC_PHANTOM if a phantom blob is encountered while trying to
3694 annotate.
3695
3696 opt->out() may return arbitrary non-0 result codes, in which case
3697 the returned code is propagated to the caller of this function.
3698
3699 Results are undefined if either argument is invalid or opt->out is
3700 NULL.
3701*/
3703 fsl_annotate_opt const * opt );
3704
3705
3706/** Convenience typedef and forward decl. */
3708
3710 /**
3711 The number of phantom artifacts seen during rebuild.
3712 */
3714 /**
3715 Counts of each blob type seen during rebuild. The FSL_SATYPE_ANY
3716 slot (0) counts non-artifact blobs.
3717 */
3718 fsl_size_t counts[FSL_SATYPE_count];
3719 /**
3720 The accumulated sizes of each blob type seen during rebuild. The
3721 FSL_SATYPE_ANY slot (0) counts non-artifact blobs.
3722 */
3723 fsl_size_t sizes[FSL_SATYPE_count];
3724};
3726
3727#define fsl_rebuild_metrics_empty_m { \
3728 .phantomCount = 0, \
3729 .counts = {0,0,0,0,0,0,0,0,0}, \
3730 .sizes = {0,0,0,0,0,0,0,0,0} \
3731 }
3732
3733/**
3734 State for use with the fsl_rebuild_f() callback type.
3735*/
3737 /**
3738 Fossil context for which this rebuild is being performed.
3739 */
3741 /**
3742 The options object used for this invocation of fsl_repo_rebuild().
3743 */
3745 /**
3746 An _approximate_ upper bound on the number of files
3747 fsl_repo_rebuild() will process. This number is very likely
3748 somewhat larger than the number of times which opt->callback()
3749 will be called, but it is close enough to give some indication of
3750 how far along a rebuild is.
3751 */
3753 /**
3754 One-based counter of total artifacts processed so far. After
3755 rebuilding is finished, opt->callback will be called one final
3756 time with this value set to 0. The callback may use the value 0
3757 to recognize that this is post-rebuild step and finalize any
3758 output or whatever it wants to do.
3759 */
3761
3762 /**
3763 The `blob.rid` value of the just-processed blob. If stepNumber is 0,
3764 this will be 0.
3765 */
3767
3768 /**
3769 The size of the just-processed blob, -1 if it is a phantom
3770 blob, or 0 when this object is part of a FSL_MSG_REBUILD_DONE
3771 message.
3772 */
3774
3775 /**
3776 Set to FSL_SATYPE_INVALID if the just-processed blob
3777 is _not_ a fossil artifact, else false. This will never be
3778 set to FSL_SATYPE_ANY.
3779 */
3781
3782 /**
3783 This is only non-0 for FSL_MSG_REBUILD_DONE messages, in which
3784 case it holds the result code of the overall rebuild process.
3785 */
3787
3788 /**
3789 Metrics from the rebuild. On each rebuild step callback call,
3790 these will contain the updated metrics.
3791 */
3793};
3794/** Convenience typedef. */
3796
3797/** Initialized-with-defaults fsl_rebuild_step structure, intended for
3798 const-copy initialization. */
3799#define fsl_rebuild_step_empty_m { \
3800 .f = NULL, .opt = NULL, .artifactCount = 0, \
3801 .stepNumber = 0, .rid = 0, .blobSize = -1, \
3802 .artifactType = FSL_SATYPE_INVALID, \
3803 .errCode = 0, \
3804 .metrics = fsl_rebuild_metrics_empty_m \
3805 }
3806
3807/** Initialized-with-defaults fsl_rebuild_step structure, intended for
3808 non-const copy initialization. */
3810
3811/**
3812 Callback for use with fsl_repo_rebuild() in order to report
3813 progress. It must return 0 on success, and any non-0 results will
3814 abort the rebuild and be propagated back to the caller.
3815
3816 Each time this is called, state->stepNumber will be incremented, starting
3817 at 1. After rebuilding is complete, it is called with a stepNumber
3818 of 0 to give the callback a chance to do any final bookkeeping or output
3819 cleanup or whatever.
3820
3821 TODO: replace this with the fsl_msg interface and use
3822 fsl_msg_listener configured for the being-rebuilt fsl_cx.
3823*/
3824typedef int (*fsl_rebuild_f)(fsl_rebuild_step const * state);
3825
3826/**
3827 Options for the rebuild process.
3828*/
3830 /**
3831 Scan artifacts in a random order (generally only of use in testing
3832 the library's code). This is primarily for testing that the library
3833 can handle its inputs in an arbitrary order.
3834 */
3836 /**
3837 True if clusters should be created.
3838
3839 NOT YET IMPLEMENTED.
3840 */
3842 /**
3843 If true, the transaction started by the rebuild process will end
3844 in a rollback even on success. In that case, if a transaction is
3845 started before the rebuild is initiated, it will be left in the
3846 rolling-back state after rebuild completes.
3847 */
3849};
3850
3851/** Initialized-with-defaults fsl_rebuild_opt structure, intended for
3852 const-copy initialization. */
3853#define fsl_rebuild_opt_empty_m {\
3854 .randomize=false, .createClusters=false, .dryRun=false \
3855}
3856
3857/** Initialized-with-defaults fsl_rebuild_opt structure, intended for
3858 non-const copy initialization. */
3860
3861/**
3862 "Rebuilds" the current repository database. This involves _at least_
3863 the following:
3864
3865 - DROPPING all transient repository tables. ALL tables in the db
3866 which do not specifically belong to fossil and do not start with
3867 the name `fx_` _will be dropped_.
3868
3869 - Recreating all transient tables from immutable state in the
3870 database.
3871
3872 - Updating the schema, if needed, from "older" versions of the
3873 fossil schema to the "current" one. This library does not
3874 currently check for updates which need to be made to a decade-old
3875 schema, however! That is, schema changes which were introduced
3876 10+ years ago are not currently addressed by this library
3877 because, frankly, it's not expected that anyone using this
3878 library will be using it with such ancient repositories (and
3879 those who do can rebuild it once with fossil(1) to update it).
3880
3881 - Crosslinking all blobs which appear to be artifacts (meaning they
3882 can be parsed as such). Any crosslink handlers registered via
3883 fsl_xlink_listener() will be called.
3884
3885 If opt is NULL then fsl_rebuild_opt_empty is used.
3886
3887 Returns 0 on success, non-0 on error (with any number of potential
3888 result codes from the db or crosslinking layers). It pushes its own
3889 transaction and will roll that back on non-0, so it "shouldn't"
3890 leave a mess on error. On error it does _not_ put any higher-level
3891 transaction into rollback mode.
3892
3893 If opt->dryRun is true then it also rolls back the transaction but
3894 it is not treated as an error and the rollback does not affect
3895 higher levels of the transaction stack
3896
3897 During the rebuild process, fsl_msg messages of types
3898 FSL_MSG_REBUILD_STEP and FSL_MSG_REBUILD_DONE may be fired. The
3899 latter is only fired if the former is.
3900
3901 This operation honors interruption via fsl_cx_interrupt() but, due
3902 to intricacies of timing, it's possible that a triggered interrupt
3903 gets trumped by another error which happens while the check for the
3904 interrupt flag is pending. In both cases this function could return
3905 a non-0 code, though.
3906*/
3908
3909/**
3910 Tries to determine the branch name of the given rid, which is assumed to
3911 refer to a checkin artifact. If it cannot find one and doFallback
3912 is true then it looks for the `main-branch` repository-level config
3913 setting and uses that (falling back to "trunk" is that setting is not set).
3914
3915 On success it returns 0 and sets `*zOut` to the branch name,
3916 transfering ownership of those bytes to the caller (who must
3917 eventually pass them to fsl_free()). If doFallback is false and no
3918 direct branch name is found then it sets `*zOut` to NULL. If
3919 doFallback is true then, on success, `*zOut` will always be set to
3920 some non-NULL value. On error `*zOut` is not modified.
3921
3922 On error it may return FSL_RC_NOT_A_REPO, FSL_RC_OOM, or any number
3923 of db-side error codes.
3924*/
3926 bool doFallback, char ** zOut );
3927
3928/** Convenience typedef and obligatory forward declaration. */
3930
3931/**
3932 Callback type for use with fsl_cidiff(). It must return 0 on
3933 success or a value from the fsl_rc_e enum on error. On error it
3934 "should" update the error state in the corresponding fsl_cx object
3935 by passing state->f to fsl_cx_err_set() (or equivalent).
3936*/
3937typedef int (*fsl_cidiff_f)(fsl_cidiff_state const *state);
3938
3939/**
3940 Options for use with fsl_cidiff()
3941*/
3943 /**
3944 Checkin version (RID) for "version 1".
3945 */
3947 /**
3948 Checkin version (RID) for "version 2". This checkin need not have
3949 any relationship with version 1, in terms of SCM-side lineage.
3950 */
3952 /**
3953 Callback to call on each iteration step.
3954 */
3956 /**
3957 Opaque state for the callback. It can be accessed
3958 from the callback via arg->opt->callbackState.
3959 */
3961};
3962
3963/** Convenience typedef. */
3965
3966/** Initialized-with-defaults fsl_cidiff_opt structure, intended for
3967 const-copy initialization. */
3968#define fsl_cidiff_opt_empty_m {0,0,0,0}
3969
3970/** Initialized-with-defaults fsl_cidiff_opt structure, intended for
3971 non-const copy initialization. */
3973
3974/**
3975 Descriptors for the type of information being reported for each
3976 step of fsl_cidiff() iteration, as reported via the
3977 fsl_cidiff_state::changes attribute.
3978*/
3980/**
3981 Indicates that the v1 and v2 files are the same. Specifically,
3982 this means:
3983
3984 - Same current names, compared case-sensitively.
3985 fsl_card_F::priorName values are ignored for this
3986 - Same permissions.
3987 - Same hash.
3988*/
3990/**
3991 Indicates that the hashes of the v1 and v2 files
3992 differ.
3993*/
3995/**
3996 Indicates that the v2 file was renamed.
3997
3998 Caveats:
3999
4000 - If v1 and v2 are not immediate relatives in the SCM DAG
4001 sense. e.g. when comparing a version X and unrelated version Y,
4002 or version X and X+30, it is possible that a rename goes
4003 unreported via fsl_cidiff or that it gets misdiagnosed. e.g. if
4004 version X renames file A to B and version X+100 renames file C to
4005 A, it will be reported as a rename. Detecting the true reality of
4006 such cases is remarkably challenging, requiring going through the
4007 entire history which links v1 and v2.
4008
4009 - Pedantically speaking, if v1 and v2 are unrelated in the SCM
4010 DAG, "renames" are not possible but will be reported as such
4011 if their names happen to match up.
4012*/
4014/**
4015 Indicates that the permissions of the current file
4016 differ between v1 and v2. This is only set if
4017 both versions have a given file (by name, as opposed
4018 to hash).
4019*/
4021/**
4022 Indicates that the file is in v2 but not v1. If v1 and v2
4023 are unrelated versions or are not immediate DAG neighbors,
4024 this might also indicate that a file from v1 was renamed
4025 in v2.
4026*/
4028/**
4029 Indicates that the file is in v1 but not v2. If v1 and v2
4030 are unrelated versions or are not immediate DAG neighbors,
4031 this might also indicate that a file from v1 was renamed
4032 in v2.
4033*/
4035};
4036/** Convenience typedef. */
4038/**
4039 Holds the state for a single iteration step of fsl_cidiff.
4040*/
4042 /**
4043 The associated fsl_cx instance.
4044 */
4046 /**
4047 The options object passed to fsl_cidiff().
4048 */
4050 /**
4051 Denotes the type of this step in the iteration.
4052
4053 Before fsl_cidiff() starts its loop over F-card changes,
4054 it calls the callback once with this value set to 0. The intent is to
4055 give the caller an opporuntity to do any required setup, e.g.
4056 outputing a report header. The
4057 fc1 and fc2 members will both be NULL, but the d1 and d2
4058 members will be set.
4059
4060 For each step of the F-card iteration, stepType will be set to
4061 FSL_RC_STEP_ROW.
4062
4063 After successful difference iteration, fsl_cidiff() calls its
4064 callback with stepType set to FSL_RC_STEP_DONE. The intent is to
4065 give the caller an opporuntity to do any required cleanup, e.g.
4066 outputing a report footer. The fc1 and fc2 members will both be
4067 NULL, but the d1 and d2 members will be set.
4068 */
4070 /**
4071 Describes the change(s) being reported by the current
4072 iteration step, as a bitmask of fsl_cidiff_e values.
4073 */
4075 /**
4076 The file, if any, corresponding to this->v1. This will be NULL
4077 this->changeType is FSL_CIDIFF_FILE_ADDED.
4078 */
4080 /**
4081 The file, if any, corresponding to this->v2. This will be NULL
4082 this->changeType is FSL_CIDIFF_FILE_REMOVED.
4083 */
4085 /**
4086 The deck corresponding to this->opt->v1. It is strictly forbidden
4087 for this->callback to manipulate this object. Specifically, any
4088 traversal of its F-card list will invalidate the iteration being
4089 done by fsl_cidiff(). Read-only operations on other state of the
4090 deck are legal.
4091 */
4092 fsl_deck const * d1;
4093 /**
4094 The deck corresponding to this->opt->v2. See the docs for
4095 this->d1 for important details.
4096 */
4097 fsl_deck const * d2;
4098};
4099
4100/** Initialized-with-defaults fsl_cidiff_state structure, intended for
4101 const-copy initialization. */
4102#define fsl_cidiff_state_empty_m {\
4103 NULL/*f*/,NULL/*opt*/, \
4104 0/*stepType*/,FSL_CIDIFF_NONE/*changes*/, \
4105 NULL/*fc1*/,NULL/*fc2*/, \
4106 NULL/*d1*/,NULL/*d2*/ \
4107 }
4108
4109/** Initialized-with-defaults fsl_cidiff_state structure, intended for
4110 non-const copy initialization. */
4112
4113/**
4114 A utility for reporting the differences between the manifests of
4115 two checkins.
4116
4117 This loads the fsl_deck instances for each version opt->v1 and
4118 opt->v2, then calls opt->callback for each step of the
4119 difference-checking process. It only inspects and reports the
4120 difference between _exactly_ v1 and _exactly_ v2, not the
4121 difference between the chain of SCM DAG relatives (if any) between
4122 the two.
4123
4124 It is not required that v1 and v2 be related in the SCM DAG but its
4125 report of differences may be misleading if v1 and v2 are either
4126 unrelated or separated by more than 1 step in the DAG. See the docs
4127 for fsl_cidiff_e for cases known to be potentially confusing.
4128
4129 Returns 0 on success. If the callback returns non-0, that result is
4130 propagated back to the caller. It may otherwise return any number of
4131 othe result codes including, but not limited to:
4132
4133 - FSL_RC_OOM on allocation error
4134
4135 - FSL_RC_NOT_A_REPO if f has no opened repository.
4136
4137 - FSL_RC_TYPE if either of the given versions is not a checkin.
4138
4139 - FSL_RC_NOT_FOUND if either of given versions is not found in the
4140 repository.
4141
4142
4143 Potential TODO: add fsl_deck_diff() which takes two decks, instead
4144 of RIDs, to compare. This function would just be a proxy for that
4145 one, loading the given RIDs and passing on the decks. That would
4146 require a significantly larger set of possible change-type values
4147 and would require much type-specific handling (e.g. maybe reporting
4148 J-card differences for a pair of ticket decks).
4149*/
4151
4152
4153/**
4154 Configuration parameters for fsl_repo_create(). Always
4155 copy-construct these from fsl_repo_create_opt_empty
4156 resp. fsl_repo_create_opt_empty_m in order to ensure proper
4157 behaviour vis-a-vis default values.
4158
4159 TODOs:
4160
4161 - Add project name/description, and possibly other
4162 configuration bits.
4163
4164 - Allow client to set password for default user (currently set
4165 randomly, as fossil(1) does).
4166*/
4168 /**
4169 The file name for the new repository.
4170 */
4171 char const * filename;
4172 /**
4173 Fossil user name for the admin user in the new repo. If NULL,
4174 defaults to the Fossil context's user (see
4175 fsl_cx_user_get()). If that is NULL, it defaults to
4176 "root" for historical reasons.
4177 */
4178 char const * username;
4179
4180 /**
4181 The comment text used for the initial commit. If NULL or empty
4182 (starts with a NUL byte) then no initial check is
4183 created. fossil(1) is largely untested with that scenario (but
4184 it seems to work), so for compatibility it is not recommended
4185 that this be set to NULL.
4186
4187 The default value (when copy-initialized) is "egg". There's a
4188 story behind the use of "egg" as the initial checkin comment,
4189 and it all started with a typo: "initial chicken"
4190 */
4191 char const * commitMessage;
4192
4193 /**
4194 Mime type for the commit message (manifest N-card). Manifests
4195 support this but fossil(1) has never (as of 2025-07) made use of
4196 it. It is provided for completeness but should, for
4197 compatibility's sake, probably not be set, as the fossil UI may
4198 not honor it. The implied default is text/x-fossil-wiki. Other
4199 ostensibly legal values include text/plain and text/x-markdown.
4200 This API will accept any value, but results are technically
4201 undefined with any values other than those listed above.
4202 */
4204
4205 /**
4206 If not NULL and not empty, fsl_repo_create() will use this
4207 repository database to copy the configuration, copying over
4208 the following settings:
4209
4210 - The reportfmt table, overwriting any existing entries.
4211
4212 - The user table fields (cap, info, mtime, photo) are copied for
4213 the "system users": anonymous, nobody, developer, reader.
4214
4215 - The vast majority of the config table is copied, arguably more
4216 than it should (e.g. the 'manifest' setting).
4217 */
4218 char const * configRepo;
4219
4220 /**
4221 If false, fsl_repo_create() will fail if this->filename
4222 already exists.
4223 */
4225
4226 /**
4227 If true, the new repo will not have a "project-code" config
4228 entry. Only set this to true when the next operation on this repo
4229 will be an inbound clone.
4230 */
4232};
4234
4235/** Initialized-with-defaults fsl_repo_create_opt struct, intended
4236 for in-struct initialization. */
4237#define fsl_repo_create_opt_empty_m { \
4238 .filename=NULL, \
4239 .username=NULL, \
4240 .commitMessage="egg", \
4241 .commitMessageMimetype=NULL, \
4242 .configRepo=NULL, \
4243 .allowOverwrite=false, \
4244 .elideProjectCode=false \
4245 }
4246
4247/** Initialized-with-defaults fsl_repo_create_opt struct, intended
4248 for copy-initialization. */
4250
4251/**
4252 Creates a new repository database using the options provided in the
4253 second argument. If f is not NULL, it must be a valid context
4254 instance, though it need not have an opened checkout/repository. If
4255 f has an opened repo or checkout, this routine closes them but that
4256 closing _will fail_ if a transaction is currently active.
4257
4258 If f is NULL, a temporary context is used for creating the
4259 repository, in which case the caller will not have access to
4260 detailed error information (only the result code) if this operation
4261 fails. In that case, the resulting repository file will, on
4262 success, be found at the location referred to by opt.filename.
4263
4264 The opt argument may not be NULL.
4265
4266 If opt->allowOverwrite is false (0) and the file exists, it fails
4267 with FSL_RC_ALREADY_EXISTS, otherwise is creates/overwrites the
4268 file. This is a destructive operation if opt->allowOverwrite is
4269 true, so be careful: the existing database will be truncated and
4270 re-created.
4271
4272 This operation installs the various "static" repository schemas
4273 into the db, sets up some default settings, and installs a
4274 default user.
4275
4276 This operation always closes any repository/checkout opened by f
4277 because setting up the new db requires wiring it to f to set up
4278 some of the db-side infrastructure. The one exception is if
4279 argument validation fails, in which case f's repo/checkout-related
4280 state are not modified. Note that closing will fail if a
4281 transaction is currently active and that, in turn, will cause this
4282 operation to fail.
4283
4284 See the fsl_repo_create_opt docs for more details regarding the
4285 creation options.
4286
4287 On success, 0 is returned and f (if not NULL) is left with the
4288 new repository opened and ready for use. On error, f's error
4289 state is updated and any number of the FSL_RC_xxx codes may be
4290 returned - there are no less than 30 different _potential_ error
4291 conditions on the way to creating a new repository.
4292
4293 If initialization of the repository fails, this routine will
4294 attempt to remove its partially-initialize corpse from the
4295 filesystem but will ignore any errors encountered while doing so.
4296
4297 Example usage:
4298
4299 ```
4300 fsl_repo_create_opt opt = fsl_repo_create_opt_empty;
4301 int rc;
4302 opt.filename = "my.fossil";
4303 // ... any other opt.xxx you want to set, e.g.:
4304 // opt.user = "fred";
4305 // Assume fsl is a valid fsl_cx instance:
4306 rc = fsl_repo_create(fsl, &opt);
4307 if(rc) { ...error... }
4308 else {
4309 fsl_db * db = fsl_cx_db_repo(f);
4310 assert(db); // == the new repo db
4311 ...
4312 }
4313 ```
4314
4315 @see fsl_repo_open()
4316 @see fsl_repo_close()
4317*/
4319
4320/**
4321 UNTESTED.
4322
4323 Returns true if f has an opened repository database which is
4324 opened in read-only mode, else returns false.
4325*/
4327
4328/**
4329 Searches for matching blob records for a fossil ticket ID. (A
4330 ticket's ID is the value of its K-card.) The given ticket ID must
4331 be a full-length ticket ID (40 characters of lower-case hex) or an
4332 unambiguous prefix.
4333
4334 If at least one match is found, it returns 0 and updates the 3rd
4335 argument: `*ridList` is assigned to an array of fsl_id_t
4336 (`blob.rid` values) terminated by an entry with the value
4337 0. Ownership of the array is passed to the caller, who must
4338 eventually pass it to fsl_free(). The entries are ordered from
4339 oldest to newest (based on their `tagxref.mtime` value).
4340
4341 On error it may return:
4342
4343 - FSL_RC_OOM on allocation error.
4344 - FSL_RC_RANGE if the given ticket ID is longer than FSL_STRLEN_SHA1.
4345 - FSL_RC_AMBIGUOUS if the ticket ID prefix would match multiple distinct
4346 ticket IDs. This result is not possible if passed a full-length ticket
4347 ID.
4348 - FSL_RC_NOT_FOUND if no match is found.
4349 - FSL_RC_NOT_A_REPO if f has no repository opened.
4350 - Any number of db-related errors if something goes horribly wrong
4351 in the db layer.
4352
4353 On error, the 3rd argument is not modified.
4354*/
4355FSL_EXPORT int fsl_tkt_id_to_rids(fsl_cx * f, char const * tktId,
4356 fsl_id_t ** ridList);
4357
4358/**
4359 Models user permissions precisely as fossil(1) does. Most of these
4360 do not apply to the library - they are "app-level" permissions.
4361 Some very few are honored by the library, namely those relevant for
4362 sync support. The app-level permissions are exposed here so that
4363 app-level code can handle those in ways compatible with fossil(1),
4364 while leaving the library to handle the permission storage (via the
4365 `user.cap` repository db field).
4366*/
4368 bool setup; /* s: use Setup screens on web interface */
4369 bool admin; /* a: administrative permission */
4370 bool password; /* p: change password */
4371 bool write; /* i: xfer inbound. check-in */
4372 bool read; /* o: xfer outbound. check-out */
4373 bool hyperlink; /* h: enable the display of hyperlinks */
4374 bool clone; /* g: clone */
4375 bool readWiki; /* j: view wiki via web */
4376 bool newWiki; /* f: create new wiki via web */
4377 bool appendWiki; /* m: append to wiki via web */
4378 bool writeWiki; /* k: edit wiki via web */
4379 bool moderateWiki; /* l: approve and publish wiki content (Moderator) */
4380 bool readTicket; /* r: view tickets via web */
4381 bool newTicket; /* n: create new tickets */
4382 bool appendTicket; /* c: append to tickets via the web */
4383 bool writeTicket; /* w: make changes to tickets via web */
4384 bool moderateTicket; /* q: approve and publish ticket changes (Moderator) */
4385 bool attach; /* b: add attachments */
4386 bool ticketReport; /* t: create new ticket report formats */
4387 bool readAddr; /* e: read email addresses or other private data */
4388 bool zip; /* z: download zipped artifact via /zip URL */
4389 bool privateContent; /* x: can send and receive private content */
4390 bool writeUnversioned; /* y: can push unversioned content */
4391 bool readForum; /* 2: Read forum posts */
4392 bool writeForum; /* 3: Create new forum posts */
4393 bool trustedForum; /* 4: Post to forums not subject to moderation */
4394 bool moderateForum; /* 5: Moderate (approve or reject) forum posts */
4395 bool adminForum; /* 6: Grant capability 4 to other users */
4396 bool emailAlert; /* 7: Sign up for email notifications */
4397 bool announce; /* A: Send announcements */
4398 bool chat; /* C: read or write the chatroom */
4399 bool debug; /* D: show extra Fossil debugging features */
4400 /* These last two represent capabilities inherited from predefined
4401 users. */
4402 bool xReader; /* u: Inherit all privileges of "reader" */
4403 bool xDeveloper; /* v: Inherit all privileges of "developer" */
4404};
4405
4406/**
4407 Helper for mass-handling of fsl_uperm permissions (e.g. generating
4408 switch/case blocks). Usage:
4409
4410 1) #define a macro which takes two argument: the fsl_uperm member
4411 name (identifier) and its corresponding capabilities character
4412 (as a char literal).
4413
4414 2) Invoke this macro, passing it the name of (1).
4415
4416 The (1) macro will be invoked one time per fsl_uperm member,
4417 passing it (memberName,aChar). No commas or semicolons are emited
4418 between calls, so they need to be included in the definition of (1)
4419 if they're relevant.
4420
4421 This macro does not include the "inehrits from" permissions
4422 (xReader, xDeveloper). Use fsl_uperm_map_inherited(M) or
4423 fsl_uperm_map_all(M) to include those.
4424*/
4425#define fsl_uperm_map_base(M) \
4426 M(setup,'s') M(admin,'a') M(password,'p') \
4427 M(write,'i') M(read,'o') M(hyperlink,'h') M(clone,'g') \
4428 M(readWiki,'j') M(newWiki,'f') M(appendWiki,'m') M(writeWiki,'k') \
4429 M(moderateWiki,'l') M(readTicket,'r') M(newTicket,'n') M(appendTicket,'c') \
4430 M(writeTicket,'w') M(moderateTicket,'q') M(attach,'b') M(ticketReport,'t') \
4431 M(readAddr,'e') M(zip,'z') M(privateContent,'x') M(writeUnversioned,'y') \
4432 M(readForum,'2') M(writeForum,'3') M(trustedForum,'4') M(moderateForum,'5') \
4433 M(adminForum,'6') M(emailAlert,'7') M(announce,'A') M(chat,'C') \
4434 M(debug,'D')
4435
4436/**
4437 Like fsl_uperm_map_base() but only includes the "inherits from"
4438 mebmers.
4439*/
4440#define fsl_uperm_map_inherited(M) \
4441 M(xReader,'u') M(xDeveloper,'v')
4442
4443#define fsl_uperm_map_all(M) \
4444 fsl_uperm_map_base(M) fsl_uperm_map_inherited(M)
4445
4446/** @internal */
4447#define fsl__uperm_map_init(M,CH) .M=false,
4448
4449/**
4450 Const-copy initializer for a fsl_uperm.
4451*/
4452#define fsl_uperm_empty_m { fsl_uperm_map_all(fsl__uperm_map_init) }
4453
4454/**
4455 A fsl_uperm instance with all members set to false.
4456*/
4457extern const fsl_uperm fsl_uperm_empty;
4458/**
4459 A fsl_uperm instance with all members set to true except for the
4460 "inherits from" properties (xReader and xDeveloper), as those
4461 permissions are already implied in the setting of all other
4462 permissions to true.
4463*/
4464extern const fsl_uperm fsl_uperm_all;
4465
4466/**
4467 Adds any permissions specified in zCap to pTgt. It does not
4468 modify permissions which are not in zCap.
4469
4470 Returns 0 on success, non-0 on error. If zCap contains any
4471 unhandled characters it returns FSL_RC_RANGE, with the exception of
4472 spaces and tabs, which it ignores. It is not an error if zCap is
4473 empty or contains only spaces/tabs.
4474
4475 If it returns non-0, pTgt's state is not well-defined. It may have
4476 been partially updated before the failure.
4477
4478 Any given permission letter may imply other permissions. e.g. the
4479 'a' and 's' permissions imply most others.
4480
4481 f is optional (may be NULL) unless zCap contains 'u' or 'v', in
4482 which case f is required in order to collect the permissions for
4483 the the "reader" resp. "developer" user. If f is NULL in those
4484 cases, FSL_RC_MISUSE is returned:
4485*/
4486FSL_EXPORT int fsl_uperm_add(fsl_cx * f, fsl_uperm * pTgt, char const *zCap);
4487
4488
4489/**
4490 Fetches f's current project code. On success, assigns it to *pOut
4491 and returns 0. Caches the result for future calls. Each repository
4492 has a project code which is shared across all of its clones.
4493*/
4494FSL_EXPORT int fsl_repo_project_code( fsl_cx * f, char const **pOut );
4495
4496
4497#if defined(__cplusplus)
4498} /*extern "C"*/
4499#endif
4500#endif
4501/* ORG_FOSSIL_SCM_FSL_REPO_H_INCLUDED */
int32_t fsl_id_t
fsl_id_t is a signed integer type used to store database record IDs.
Definition config.h:271
uint64_t fsl_size_t
fsl_size_t is an unsigned integer type used to denote absolute ranges and lengths.
Definition config.h:192
int64_t fsl_time_t
The type used to represent type values.
Definition config.h:296
int64_t fsl_int_t
fsl_int_t is a signed integer type used to denote "relative" ranges and lengths, or to tell a routine...
Definition config.h:143
#define FSL_EXPORT
Definition config.h:66
fsl_fileperm_e
File permissions flags supported by fossil manifests.
Definition core.h:511
#define E(N, V, H)
Definition core.h:497
fsl_satype_e
An enumeration of the types of structural artifacts used by Fossil.
Definition core.h:1676
int(* fsl_deck_xlink_f)(fsl_deck *d, void *state)
A callback interface for manifest crosslinking, so that we can farm out the updating of the event tab...
Definition repo.h:1726
FSL_EXPORT const fsl_repo_create_opt fsl_repo_create_opt_empty
Initialized-with-defaults fsl_repo_create_opt struct, intended for copy-initialization.
Definition repo.h:4249
FSL_EXPORT int fsl_deck_R_set(fsl_deck *mf, char const *md5)
Functionally identical to fsl_deck_B_set() except that it sets the R-card.
FSL_EXPORT int fsl_branch_create(fsl_cx *f, fsl_branch_opt const *opt, fsl_id_t *newRid)
Creates a new branch in f's repository.
FSL_EXPORT int fsl_deck_R_calc2(fsl_deck *d, char **tgt)
A variant of fsl_deck_R_calc() which calculates the given deck's R-card but does not assign it to the...
FSL_EXPORT int fsl_deck_F_set(fsl_deck *d, char const *name, fsl_uuid_cstr uuid, fsl_fileperm_e perm, char const *priorName)
Works mostly like fsl_deck_F_add() except that:
int fsl_annotate_step_f_fossilesque(void *state, fsl_annotate_opt const *opt, fsl_annotate_step const *step)
A fsl_annotate_step_f() impl.
fsl_tagtype_e
Artifact tag types used by the Fossil framework.
Definition repo.h:107
@ FSL_TAGTYPE_ADD
The "add tag" indicator, a.k.a.
Definition repo.h:119
@ FSL_TAGTYPE_PROPAGATING
The "propagating tag" indicator.
Definition repo.h:123
@ FSL_TAGTYPE_INVALID
Sentinel value for use with constructors/initializers.
Definition repo.h:111
@ FSL_TAGTYPE_CANCEL
The "cancel tag" indicator, a.k.a.
Definition repo.h:115
FSL_EXPORT int fsl_deck_to_json(fsl_deck const *d, fsl_output_f fn, void *fState)
Emits a JSON representation of the given deck to the given output routine.
FSL_EXPORT int fsl_mtime_of_manifest_file(fsl_cx *f, fsl_id_t vid, fsl_id_t fid, fsl_time_t *pMTime)
Compute the "mtime" of the file given whose blob.rid is "fid" that is part of check-in "vid".
FSL_EXPORT fsl_card_J * fsl_card_J_malloc(bool isAppend, char const *field, char const *value)
Allocates a new J-card record instance.
FSL_EXPORT fsl_card_T * fsl_card_T_malloc(fsl_tagtype_e tagType, fsl_uuid_cstr uuid, char const *name, char const *value)
Allocates a new fsl_card_T instance.
FSL_EXPORT fsl_id_t fsl_tag_id(fsl_cx *f, char const *tag, bool create)
Searches for a repo.tag entry given name in the given context's repository db.
const fsl_annotate_opt fsl_annotate_opt_empty
Initialized-with-defaults fsl_annotate_opt structure, intended for non-const copy initialization.
FSL_EXPORT int fsl_deck_A_set(fsl_deck *mf, char const *filename, char const *target, fsl_uuid_cstr uuidSrc)
Sets the A-card for an Attachment (FSL_SATYPE_ATTACHMENT) deck.
FSL_EXPORT int fsl_deck_W_set(fsl_deck *mf, char const *content, fsl_int_t len)
Semantically identical fsl_deck_B_set() but sets the W-card.
FSL_EXPORT int fsl_annotate(fsl_cx *f, fsl_annotate_opt const *opt)
UNDER CONSTRUCTION.
FSL_EXPORT int fsl_deck_F_next(fsl_deck *d, fsl_card_F const **f)
Fetches the next F-card entry from d.
FSL_EXPORT void fsl_deck_clean2(fsl_deck *deck, fsl_buffer *tgt)
A variant of fsl_deck_clean() which "returns" its content buffer for re-use by transferring,...
FSL_EXPORT char const * fsl_schema_repo2(void)
Returns the raw SQL code for the "transient" parts of a Fossil repository database - any parts which ...
const fsl_uperm fsl_uperm_empty
A fsl_uperm instance with all members set to false.
FSL_EXPORT int fsl_leaves_compute(fsl_cx *f, fsl_id_t vid, fsl_leaves_compute_e leafMode)
Creates a temporary table named "leaves" if it does not already exist, else empties it.
FSL_EXPORT const fsl_card_T fsl_card_T_empty
Defaults-initialized fsl_card_T instance.
Definition repo.h:2302
FSL_EXPORT bool fsl_content_is_private(fsl_cx *f, fsl_id_t rid)
Returns true if the given rid is marked as PRIVATE in f's current repository.
FSL_EXPORT bool fsl_is_shunned_uuid(fsl_cx *f, fsl_uuid_cstr zUuid)
Return true if the given artifact ID should is listed in f's shun table or if zUuid is an SHA1 has an...
FSL_EXPORT int fsl_deck_M_add(fsl_deck *mf, fsl_uuid_cstr uuid)
Adds the given UUID as an M-card entry.
FSL_EXPORT int fsl_repo_blob_lookup(fsl_cx *f, fsl_buffer const *src, fsl_id_t *ridOut, fsl_uuid_str *hashOut)
This is a wrapper around fsl_cx_hash_buffer() which looks for a matching artifact for the given input...
FSL_EXPORT int fsl_deck_F_add(fsl_deck *d, char const *name, fsl_uuid_cstr uuid, fsl_fileperm_e perm, char const *priorName)
Adds a new F-card to the given deck.
FSL_EXPORT int fsl_deck_P_add(fsl_deck *mf, fsl_uuid_cstr parentUuid)
Adds the given UUID as a parent of the given change record.
FSL_EXPORT int fsl_deck_load_rid(fsl_cx *f, fsl_deck *d, fsl_id_t rid, fsl_satype_e type)
Loads the content from given rid and tries to parse it as a Fossil artifact.
FSL_EXPORT char const * fsl_schema_ticket_reports(void)
Returns the raw SQL code for Fossil ticket reports schemas.
FSL_EXPORT int fsl_deck_derive(fsl_deck *d)
UNDER CONSTRUCTION!
int(* fsl_rebuild_f)(fsl_rebuild_step const *state)
Callback for use with fsl_repo_rebuild() in order to report progress.
Definition repo.h:3824
FSL_EXPORT char const * fsl_schema_config(void)
Returns the raw SQL code for a Fossil global config database.
FSL_EXPORT int fsl_card_F_content(fsl_cx *f, fsl_card_F const *fc, fsl_buffer *dest)
If fc->uuid refers to a blob in f's repository database then that content is placed into dest (as per...
FSL_EXPORT void fsl_card_F_list_finalize(fsl_card_F_list *li)
Frees all memory owned by li and the F-cards it contains.
fsl_cidiff_e
Descriptors for the type of information being reported for each step of fsl_cidiff() iteration,...
Definition repo.h:3979
@ FSL_CIDIFF_FILE_ADDED
Indicates that the file is in v2 but not v1.
Definition repo.h:4027
@ FSL_CIDIFF_NONE
Indicates that the v1 and v2 files are the same.
Definition repo.h:3989
@ FSL_CIDIFF_FILE_MODIFIED
Indicates that the hashes of the v1 and v2 files differ.
Definition repo.h:3994
@ FSL_CIDIFF_FILE_PERMS
Indicates that the permissions of the current file differ between v1 and v2.
Definition repo.h:4020
@ FSL_CIDIFF_FILE_REMOVED
Indicates that the file is in v1 but not v2.
Definition repo.h:4034
@ FSL_CIDIFF_FILE_RENAMED
Indicates that the v2 file was renamed.
Definition repo.h:4013
fsl_cherrypick_type_e
Types of cherrypick merges.
Definition repo.h:2307
@ FSL_CHERRYPICK_INVALID
Sentinel value.
Definition repo.h:2309
@ FSL_CHERRYPICK_ADD
Indicates a cherrypick merge.
Definition repo.h:2311
@ FSL_CHERRYPICK_BACKOUT
Indicates a cherrypick backout.
Definition repo.h:2313
FSL_EXPORT char const * fsl_schema_ticket(void)
Returns the raw SQL code for a Fossil checkout db's default core ticket-related tables.
FSL_EXPORT bool fsl_rid_is_leaf(fsl_cx *f, fsl_id_t rid)
Returns true if the checkin with the given rid is a leaf, false if not.
FSL_EXPORT int fsl_repo_open(fsl_cx *f, char const *repoDbFile)
Opens the given db file name as f's repository.
FSL_EXPORT fsl_id_t fsl_uuid_to_rid(fsl_cx *f, char const *uuid)
Searches f's repo database for the a blob with the given uuid (any unique UUID prefix).
FSL_EXPORT int fsl_uperm_add(fsl_cx *f, fsl_uperm *pTgt, char const *zCap)
Adds any permissions specified in zCap to pTgt.
FSL_EXPORT char const * fsl_schema_forum(void)
Returns the raw SQL code for the "forum" parts of a Fossil repository database.
FSL_EXPORT int fsl_deck_J_add(fsl_deck *mf, bool isAppend, char const *key, char const *value)
Adds a J-card to the given deck, setting/updating the given ticket property key to the given value.
FSL_EXPORT int fsl_deck_C_set(fsl_deck *mf, char const *comment, fsl_int_t cardLen)
Semantically identical to fsl_deck_B_set() but sets the C-card and does not place a practical limit o...
FSL_EXPORT fsl_int_t fsl_leaves_computed_count(fsl_cx *f)
Requires that a prior call to fsl_leaves_compute() has succeeded, else results are undefined.
FSL_EXPORT int fsl_repo_leaves_rebuild(fsl_cx *f)
Recompute/rebuild the entire repo.leaf table.
FSL_EXPORT int fsl_content_make_public(fsl_cx *f, fsl_id_t rid)
Marks the given rid public, if it was previously marked as private.
FSL_EXPORT int fsl_deck_L_set(fsl_deck *mf, char const *title, fsl_int_t len)
Semantically identical fsl_deck_B_set() but sets the L-card.
FSL_EXPORT char fsl_tag_prefix_char(fsl_tagtype_e t)
Returns one of '-', '+', or '*' for a valid input parameter, 0 for any other value.
FSL_EXPORT bool fsl_might_be_artifact(fsl_buffer const *src)
Quickly determines whether the content held by the given buffer "might" be a structural artifact.
FSL_EXPORT const fsl_cidiff_opt fsl_cidiff_opt_empty
Initialized-with-defaults fsl_cidiff_opt structure, intended for non-const copy initialization.
Definition repo.h:3972
FSL_EXPORT bool fsl_repo_is_readonly(fsl_cx const *f)
UNTESTED.
FSL_EXPORT bool fsl_rid_is_version(fsl_cx *f, fsl_id_t rid)
Returns true if, according to f's current repo's [event] table, rid refers to a checkin,...
FSL_EXPORT int fsl_deck_parse(fsl_deck *d, fsl_buffer *src)
Parses src as Control Artifact content and populates d with it.
FSL_EXPORT int fsl_branch_of_rid(fsl_cx *f, fsl_id_t rid, bool doFallback, char **zOut)
Tries to determine the branch name of the given rid, which is assumed to refer to a checkin artifact.
FSL_EXPORT int fsl_delta_s2r(fsl_cx *f, fsl_id_t deltaRid, fsl_id_t *rv)
The counterpart of fsl_delta_r2s(): for a given delta.srcid, return the associated delta....
FSL_EXPORT int fsl_delta_r2s(fsl_cx *f, fsl_id_t deltaRid, fsl_id_t *rv)
Looks for the delta table record where rid==deltaRid, and returns that record's srcid via *rv.
int(* fsl_card_F_visitor_f)(fsl_card_F const *fc, void *state)
Callback type for use with fsl_deck_F_foreach() and friends.
Definition repo.h:873
FSL_EXPORT char const * fsl_schema_repo1(void)
Returns the raw SQL code for the "static" parts of a Fossil repository database.
FSL_EXPORT int fsl_repo_project_code(fsl_cx *f, char const **pOut)
Fetches f's current project code.
FSL_EXPORT int fsl_deck_D_set(fsl_deck *mf, double date)
Sets mf's D-card as a Julian Date value.
int(* fsl_cidiff_f)(fsl_cidiff_state const *state)
Callback type for use with fsl_cidiff().
Definition repo.h:3937
FSL_EXPORT int fsl_deck_F_rewind(fsl_deck *d)
Rewinds d's F-card traversal iterator and loads d's baseline manifest, if it has one (i....
FSL_EXPORT int fsl_branch_main(fsl_cx *f, char const **zOut, bool forceReload)
Checks f's repo db for a setting named 'main-branch'.
FSL_EXPORT int fsl_deck_T_add2(fsl_deck *mf, fsl_card_T *t)
Adds the given tag instance to the given manifest.
FSL_EXPORT fsl_uuid_str fsl_rid_to_uuid(fsl_cx *f, fsl_id_t rid)
The opposite of fsl_uuid_to_rid(), this returns the UUID string of the given blob record ID.
FSL_EXPORT int fsl_deck_T_add(fsl_deck *d, fsl_tagtype_e tagType, fsl_uuid_cstr uuid, char const *name, char const *value)
Adds a new T-card (tag) entry to the given deck.
FSL_EXPORT fsl_uuid_str fsl_rid_to_artifact_uuid(fsl_cx *f, fsl_id_t rid, fsl_satype_e type)
This works identically to fsl_rid_to_uuid() except that it will only resolve to a UUID if an artifact...
FSL_EXPORT bool fsl_repo_forbids_delta_manifests(fsl_cx *f)
Returns true if f's current repository has the forbid-delta-manifests setting set to a truthy value.
FSL_EXPORT int fsl_deck_F_foreach(fsl_deck *d, fsl_card_F_visitor_f cb, void *visitorState)
For each F-card in d, cb(card,visitorState) is called.
FSL_EXPORT bool fsl_wiki_page_exists(fsl_cx *f, char const *pageName)
Returns true (non-0) if f's repo database contains a page with the given name, else false.
FSL_EXPORT bool fsl_deck_has_required_cards(fsl_deck const *d)
Returns true if d contains data for all required cards, as determined by the value of d->type,...
FSL_EXPORT int fsl_deck_K_set(fsl_deck *mf, fsl_uuid_cstr uuid)
Sets the K-card (ticket ID) on the given deck.
FSL_EXPORT int fsl_cidiff(fsl_cx *f, fsl_cidiff_opt const *opt)
A utility for reporting the differences between the manifests of two checkins.
FSL_EXPORT int fsl_repo_dir_names(fsl_cx *f, fsl_id_t rid, fsl_list *tgt, bool addSlash)
Fetches the list of all directory names for a given checkin record id or (if rid is negative) the who...
FSL_EXPORT int fsl_deck_branch_set(fsl_deck *d, char const *branchName)
A convenience form of fsl_deck_T_add() which adds two propagating tags to the given deck: "branch" wi...
FSL_EXPORT int fsl_wiki_latest_rid(fsl_cx *f, char const *pageName, fsl_id_t *newRid)
Fetches the most recent RID for the given wiki page name and assigns *newId (if it is not NULL) to th...
FSL_EXPORT bool fsl_leaves_computed_has(fsl_cx *f)
Requires that a prior call to fsl_leaves_compute() has succeeded, else results are undefined.
FSL_EXPORT int fsl_sym_to_uuid(fsl_cx *f, char const *sym, fsl_satype_e type, fsl_uuid_str *rv, fsl_id_t *rid)
Similar to fsl_sym_to_rid() but on success it returns a UUID string by assigning it to *rv (if rv is ...
FSL_EXPORT const fsl_cidiff_state fsl_cidiff_state_empty
Initialized-with-defaults fsl_cidiff_state structure, intended for non-const copy initialization.
Definition repo.h:4111
FSL_EXPORT fsl_card_F const * fsl_deck_F_search(fsl_deck *d, const char *zName)
Looks for a file in a manifest or (for a delta manifest) its baseline.
FSL_EXPORT int fsl_card_is_legal(fsl_satype_e t, char card)
This function is a programmatic interpretation of this table:
FSL_EXPORT int fsl_wiki_foreach_page(fsl_cx *f, fsl_deck_visitor_f cb, void *state)
For each unique wiki page name in f's repostory, this calls cb(), passing it the manifest of the most...
FSL_EXPORT void fsl_card_T_free(fsl_card_T *t)
If t is not NULL, calls fsl_card_T_clean(t) and then passes t to fsl_free().
FSL_EXPORT const fsl_repo_extract_opt fsl_repo_extract_opt_empty
Initialized-with-defaults fsl_repo_extract_opt instance, intended for intializing new non-const insta...
Definition repo.h:2656
FSL_EXPORT int fsl_card_F_list_reserve(fsl_card_F_list *li, uint32_t n)
Ensures that the given list has capacity for at least n entries.
FSL_EXPORT fsl_card_Q * fsl_card_Q_malloc(fsl_cherrypick_type_e type, fsl_uuid_cstr target, fsl_uuid_cstr baseline)
Allocates a new cherrypick record instance.
FSL_EXPORT int fsl_content_size_v2(fsl_cx *f, fsl_id_t rid, fsl_int_t *pOut)
Given a blob RID, this function extracts its size from the blob.rid db field.
FSL_EXPORT int fsl_deck_I_set(fsl_deck *mf, fsl_uuid_cstr uuid)
Sets the 'I' card on a forum-post deck to a copy of the given UUID.
FSL_EXPORT int fsl_deck_P_add_rid(fsl_deck *mf, fsl_id_t parentRid)
A convenience wrapper around fsl_deck_P_add() which resolves the given RID to its UUID and passes it ...
FSL_EXPORT int fsl_repo_extract(fsl_cx *f, fsl_repo_extract_opt const *opt)
Iterates over the file content of a single checkin in a repository, sending the appropriate version o...
FSL_EXPORT fsl_id_t fsl_deck_P_get_id(fsl_deck *d, int index)
If d contains a P card with the given index, this returns the RID corresponding to the UUID at that i...
FSL_EXPORT int fsl_cx_schema_ticket(fsl_cx *f, fsl_buffer *pOut)
If f's opened repository has a non-empty config entry named 'ticket-table', this returns its text via...
FSL_EXPORT void fsl_deck_finalize(fsl_deck *deck)
Frees all memory owned by deck (see fsl_deck_clean()).
FSL_EXPORT int fsl_tag_an_rid(fsl_cx *f, fsl_tagtype_e tagType, fsl_id_t artifactRidToTag, char const *tagName, char const *tagValue, char const *userName, double mtime, fsl_id_t *newId)
Adds a control record to f's repositoriy that either creates or cancels a tag.
FSL_EXPORT int fsl_sym_to_rid(fsl_cx *f, char const *sym, fsl_satype_e type, fsl_id_t *rv)
Resolves client-provided symbol as an artifact's db record ID.
FSL_EXPORT int fsl_deck_unshuffle(fsl_deck *d, bool calculateRCard)
Prepares the given deck for output by ensuring that cards which need to be sorted are sorted,...
FSL_EXPORT int fsl_content_get(fsl_cx *f, fsl_id_t blobRid, fsl_buffer *tgt)
Functionally similar to fsl_content_raw() but does a lot of work to ensure that the returned blob is ...
FSL_EXPORT void fsl_card_J_free(fsl_card_J *cp)
Frees a J-card record created by fsl_card_J_malloc().
FSL_EXPORT int fsl_deck_foreach(fsl_cx *f, fsl_satype_e type, fsl_deck_visitor_f visitor, void *visitorState)
Iterates over all artifacts in f's current repository of the given type, passing each one to the give...
FSL_EXPORT int fsl_tkt_id_to_rids(fsl_cx *f, char const *tktId, fsl_id_t **ridList)
Searches for matching blob records for a fossil ticket ID.
FSL_EXPORT const fsl_card_Q fsl_card_Q_empty
Empty-initialized fsl_card_Q struct.
Definition repo.h:2337
FSL_EXPORT int fsl_rid_to_uuid2(fsl_cx *f, fsl_id_t rid, fsl_buffer *uuid)
Works like fsl_rid_to_uuid() but assigns the UUID to the given buffer, re-using its memory,...
FSL_EXPORT const fsl_deck fsl_deck_empty
Initialized-with-defaults fsl_deck structure, intended for copy initialization.
Definition repo.h:530
fsl_xlinker * fsl_xlinker_by_name(fsl_cx *f, char const *name)
Searches f's crosslink callbacks for an entry with the given name and returns that entry,...
fsl_leaves_compute_e
Flags for use with fsl_leaves_compute().
Definition repo.h:3320
@ FSL_LEAVES_COMPUTE_OPEN
Compute only leaves without the "closed" tag.
Definition repo.h:3328
@ FSL_LEAVES_COMPUTE_CLOSED
Compute only leaves with the "closed" tag.
Definition repo.h:3332
@ FSL_LEAVES_COMPUTE_ALL
Compute all leaves regardless of the "closed" tag.
Definition repo.h:3324
FSL_EXPORT const fsl_rebuild_opt fsl_rebuild_opt_empty
Initialized-with-defaults fsl_rebuild_opt structure, intended for non-const copy initialization.
Definition repo.h:3859
FSL_EXPORT fsl_deck * fsl_deck_malloc(void)
Allocates a new fsl_deck instance.
FSL_EXPORT fsl_int_t fsl_content_size(fsl_cx *f, fsl_id_t blobRid)
For the given blob.rid value, returns the blob.size value of that record via *rv.
int(* fsl_annotate_step_f)(void *state, fsl_annotate_opt const *opt, fsl_annotate_step const *step)
Callback for use with fsl_annotate().
Definition repo.h:3559
FSL_EXPORT int fsl_repo_manifest_write(fsl_cx *f, fsl_id_t manifestRid, fsl_buffer *manifest, fsl_buffer *manifestUuid, fsl_buffer *manifestTags)
This is a variant of fsl_ckout_manifest_write() which writes data regarding the given manifest RID to...
FSL_EXPORT void fsl_card_T_clean(fsl_card_T *t)
Frees up any memory owned by t and clears out t's state, but does not free t.
FSL_EXPORT bool fsl_is_reserved_fn(const char *zFilename, fsl_int_t nameLen)
Returns true if the specified file name ends with any reserved name, e.g.: FOSSIL or ....
FSL_EXPORT fsl_int_t fsl_count_nonbranch_children(fsl_cx *f, fsl_id_t rid)
Counts the number of primary non-branch children for the given check-in.
FSL_EXPORT int fsl_xlink_listener(fsl_cx *f, char const *name, fsl_deck_xlink_f cb, void *cbState)
Adds the given function as a "crosslink callback" for the given Fossil context.
FSL_EXPORT int fsl_deck_E_set(fsl_deck *mf, double date, fsl_uuid_cstr uuid)
Sets the E-card in the given deck.
const fsl_xlinker fsl_xlinker_empty
Empty-initialized fsl_xlinker struct, intended for copy intialization.
fsl_wiki_save_mode_t
A helper type for use with fsl_wiki_save(), intended primarily to help client-side code readability s...
Definition repo.h:2099
@ FSL_WIKI_SAVE_MODE_CREATE
Indicates that fsl_wiki_save() must only allow the creation of a new page, and must fail if such an e...
Definition repo.h:2104
@ FSL_WIKI_SAVE_MODE_UPDATE
Indicates that fsl_wiki_save() must only allow the update of an existing page, and will not create a ...
Definition repo.h:2109
@ FSL_WIKI_SAVE_MODE_UPSERT
Indicates that fsl_wiki_save() must allow both the update and creation of pages.
Definition repo.h:2115
FSL_EXPORT const fsl_card_F_list fsl_card_F_list_empty
Empty-initialized fsl_card_F instance for non-const copy initialization.
Definition repo.h:242
FSL_EXPORT char fsl_rid_is_a_checkin(fsl_cx *f, fsl_id_t rid)
Returns true (non-0) if f is not NULL and f has an opened repo which contains a checkin with the give...
FSL_EXPORT int fsl_deck_H_set(fsl_deck *mf, char const *comment, fsl_int_t cardLen)
Sets the 'H' card on a forum-post deck to a copy of the given comment.
FSL_EXPORT int fsl_deck_output(fsl_deck *d, fsl_output_f out, void *outputState)
Renders the given control artifact's contents to the given output function and calculates any cards w...
FSL_EXPORT void fsl_card_Q_free(fsl_card_Q *cp)
Frees a cherrypick record created by fsl_card_Q_malloc().
FSL_EXPORT int fsl_deck_N_set(fsl_deck *mf, char const *mimeType, fsl_int_t len)
Semantically identical to fsl_deck_B_set() but sets the N card.
FSL_EXPORT int fsl_content_get_sym(fsl_cx *f, char const *sym, fsl_buffer *tgt)
Uses fsl_sym_to_rid() to convert sym to a record ID, then passes that to fsl_content_get().
const fsl_xlinker_list fsl_xlinker_list_empty
Empty-initializes fsl_xlinker_list struct, intended for copy intialization.
FSL_EXPORT void fsl_deck_init(fsl_cx *cx, fsl_deck *d, fsl_satype_e type)
Must be called to initialize a newly-created/allocated deck instance.
FSL_EXPORT int fsl_deck_parse2(fsl_deck *d, fsl_buffer *src, fsl_id_t rid)
This variant of fsl_deck_parse() works identically to that function except for the 3rd argument.
FSL_EXPORT int fsl_deck_Q_add(fsl_deck *mf, int type, fsl_uuid_cstr target, fsl_uuid_cstr baseline)
Adds a Q-card record to the given deck.
FSL_EXPORT int fsl_deck_baseline_fetch(fsl_deck *d)
Loads the baseline manifest specified in d->B.uuid, if any and if necessary.
FSL_EXPORT const fsl_repo_extract_state fsl_repo_extract_state_empty
Initialized-with-defaults fsl_repo_extract_state instance, intended for non-const copy initialization...
Definition repo.h:2590
FSL_EXPORT const fsl_card_J fsl_card_J_empty
Empty-initialized fsl_card_J struct.
Definition repo.h:2273
FSL_EXPORT void fsl_deck_clean(fsl_deck *deck)
Frees all resources belonging to the given deck's members (including its parents, recursively),...
FSL_EXPORT int fsl_wiki_save(fsl_cx *f, char const *pageName, fsl_buffer const *b, char const *userName, char const *mimeType, fsl_wiki_save_mode_t creationPolicy)
Saves wiki content to f's repository db.
FSL_EXPORT const fsl_rebuild_step fsl_rebuild_step_empty
Initialized-with-defaults fsl_rebuild_step structure, intended for non-const copy initialization.
Definition repo.h:3809
FSL_EXPORT int fsl_repo_create(fsl_cx *f, fsl_repo_create_opt const *opt)
Creates a new repository database using the options provided in the second argument.
FSL_EXPORT int fsl_repo_rebuild(fsl_cx *f, fsl_rebuild_opt const *opt)
"Rebuilds" the current repository database.
FSL_EXPORT int fsl_reserved_fn_check(fsl_cx *f, const char *zPath, fsl_int_t nFile, bool relativeToCwd)
Uses fsl_is_reserved_fn() to determine whether the filename part of zPath is legal for use as an in-r...
FSL_EXPORT fsl_id_t fsl_repo_filename_fnid(fsl_cx *f, char const *filename)
Tries to determine the [filename.fnid] value for the given filename.
FSL_EXPORT char const * fsl_schema_ckout(void)
Returns the raw SQL code for a Fossil checkout database.
fsl_annotate_step_e
"Stage" flag for use with fsl_annotate_step and fsl_annotate_step_f().
Definition repo.h:3444
@ FSL_ANNOTATE_STEP_LIMITED
Indicates that the current fsl_annotate_step_f() call has only partial version information for the li...
Definition repo.h:3461
@ FSL_ANNOTATE_STEP_VERSION
Indicates that the current fsl_annotate_step_f() call is part of the "version dump" stage of the anno...
Definition repo.h:3449
@ FSL_ANNOTATE_STEP_FULL
Indicates that the current fsl_annotate_step_f() call has complete version information for the line i...
Definition repo.h:3455
FSL_EXPORT const fsl_card_F fsl_card_F_empty
Definition repo.h:2246
FSL_EXPORT int fsl_wiki_load_latest(fsl_cx *f, char const *pageName, fsl_deck *d)
Loads the artifact for the most recent version of the given wiki page, populating d with its contents...
FSL_EXPORT int fsl_deck_B_set(fsl_deck *mf, fsl_uuid_cstr uuidBaseline)
Sets or unsets (if uuidBaseline is NULL or empty) the B-card for the given manifest to a copy of the ...
FSL_EXPORT int fsl_mtime_of_F_card(fsl_cx *f, fsl_id_t vid, fsl_card_F const *fc, fsl_time_t *pMTime)
A convenience form of fsl_mtime_of_manifest_file() which looks up fc's RID based on its UUID.
FSL_EXPORT int fsl_deck_F_set_content(fsl_deck *d, char const *name, fsl_buffer const *src, fsl_fileperm_e perm, char const *priorName)
UNDER CONSTRUCTION!
fsl_tagid_e
Hard-coded IDs used by the 'tag' table of repository DBs.
Definition repo.h:132
@ FSL_TAGID_USER
DB: tag.tagname='user'.
Definition repo.h:144
@ FSL_TAGID_PRIVATE
DB: tag.tagname='private'.
Definition repo.h:156
@ FSL_TAGID_BGCOLOR
DB string tagname='bgcolor'.
Definition repo.h:136
@ FSL_TAGID_COMMENT
DB: tag.tagname='comment'.
Definition repo.h:140
@ FSL_TAGID_BRANCH
DB: tag.tagname='branch'.
Definition repo.h:164
@ FSL_TAGID_CLOSED
DB: tag.tagname='closed'.
Definition repo.h:168
@ FSL_TAGID_NOTE
DB: tag.tagname='note'.
Definition repo.h:178
@ FSL_TAGID_CLUSTER
DB: tag.tagname='cluster'.
Definition repo.h:160
@ FSL_TAGID_MAX_INTERNAL
Largest tag ID reserved for internal use.
Definition repo.h:183
@ FSL_TAGID_PARENT
DB: tag.tagname='parent'.
Definition repo.h:172
@ FSL_TAGID_DATE
DB: tag.tagname='date'.
Definition repo.h:148
@ FSL_TAGID_HIDDEN
DB: tag.tagname='hidden'.
Definition repo.h:152
FSL_EXPORT int fsl_content_raw(fsl_cx *f, fsl_id_t blobRid, fsl_buffer *tgt)
For the given blob.rid value, fetches the content field of that record and overwrites tgt's contents ...
FSL_EXPORT int fsl_deck_G_set(fsl_deck *mf, fsl_uuid_cstr uuid)
Sets the 'G' card on a forum-post deck to a copy of the given UUID.
FSL_EXPORT int fsl_tag_sym(fsl_cx *f, fsl_tagtype_e tagType, char const *symToTag, char const *tagName, char const *tagValue, char const *userName, double mtime, fsl_id_t *newId)
Equivalent to fsl_tag_an_rid() except that it takes a symbolic artifact name in place of an artifact ...
FSL_EXPORT int fsl_wiki_names_get(fsl_cx *f, fsl_list *tgt)
Fetches the list of all wiki page names in f's current repo db and appends them as new (char *) strin...
FSL_EXPORT int fsl_deck_load_sym(fsl_cx *f, fsl_deck *d, char const *symbolicName, fsl_satype_e type)
A convenience form of fsl_deck_load_rid() which uses fsl_sym_to_rid() to convert symbolicName into an...
int(* fsl_repo_extract_f)(fsl_repo_extract_state const *xstate)
A callback type for use with fsl_repo_extract().
Definition repo.h:2612
FSL_EXPORT int fsl_card_F_compare_name(fsl_card_F const *lhs, fsl_card_F const *rhs)
Given two F-card instances, this function compares their names (case-sensitively).
FSL_EXPORT fsl_id_t fsl_leaves_computed_latest(fsl_cx *f)
Requires that a prior call to fsl_leaves_compute() has succeeded, else results are undefined.
FSL_EXPORT const fsl_branch_opt fsl_branch_opt_empty
Definition repo.h:2978
FSL_EXPORT int fsl_deck_U_set(fsl_deck *mf, char const *userName)
Semantically identical fsl_deck_B_set() but sets the U-card.
FSL_EXPORT int fsl_repo_zip_sym_to_filename(fsl_cx *f, char const *sym, char const *vRootDir, char const *fileName, fsl_card_F_visitor_f progressVisitor, void *progressState)
ZIPs up a copy of the contents of a specific version from f's opened repository db.
const fsl_uperm fsl_uperm_all
A fsl_uperm instance with all members set to true except for the "inherits from" properties (xReader ...
int(* fsl_deck_visitor_f)(fsl_cx *f, fsl_deck *d, void *state)
Generic callback interface for visiting decks.
Definition repo.h:2026
FSL_EXPORT int fsl_deck_save(fsl_deck *d, bool isPrivate)
Saves the given deck into f's repository database as new control artifact content.
FSL_EXPORT int fsl_deck_R_calc(fsl_deck *d)
Calculates the value of d's R-card based on its F-cards and updates d->R.
FSL_EXPORT void fsl_leaves_computed_cleanup(fsl_cx *f)
Cleans up any db-side resources created by fsl_leaves_compute().
Configuration for use with fsl_annotate().
Definition repo.h:3582
uint32_t limitMs
An approximate number of milliseconds of processing time to limit the annotation to.
Definition repo.h:3620
fsl_annotate_step_f out
The output channel for the resulting annotation.
Definition repo.h:3653
int16_t spacePolicy
Definition repo.h:3626
uint32_t limitVersions
The maximum number of versions to search through.
Definition repo.h:3604
char const * filename
The repository-root-relative NUL-terminated filename to annotate.
Definition repo.h:3586
bool fileVersions
Output file blob versions, instead of checkin versions.
Definition repo.h:3643
bool praise
If true, include the name of the user for which each change is attributed (noting that merges show wh...
Definition repo.h:3639
fsl_id_t versionRid
The checkin from which the file's version should be selected.
Definition repo.h:3592
fsl_id_t originRid
The origin checkin version.
Definition repo.h:3600
bool dumpVersions
If true, annotation output will start with a list of all versions analyzed by the annotation process.
Definition repo.h:3649
void * outState
State for passing as the first argument to this->out().
Definition repo.h:3657
Callback state for use by fsl_annotate_step_f().
Definition repo.h:3476
uint32_t lineLength
The number of bytes in this->line.
Definition repo.h:3520
fsl_uuid_cstr versionHash
The hash of the checkin version from which this->line was pulled.
Definition repo.h:3530
int stepNumber
Step number in this annotation run.
Definition repo.h:3507
char const * username
The user name this change was attributed to, noting that merges are attributed to the one who did the...
Definition repo.h:3545
fsl_uuid_cstr fileHash
The hash of the file version from which this->line was pulled.
Definition repo.h:3525
double mtime
The mtime field from the [event] table (timeline) entry associated with this version.
Definition repo.h:3540
uint32_t lineNumber
Line number for the current file.
Definition repo.h:3511
fsl_annotate_step_e stepType
Tells the caller the "type" of annotation step this call represents.
Definition repo.h:3496
char const * line
NUL-terminated current line of the input file, minus any newline and/or carriage return.
Definition repo.h:3516
Holds options for use with fsl_branch_create().
Definition repo.h:2935
double mtime
The julian time of the branch.
Definition repo.h:2965
bool isPrivate
If true, the branch will be marked as private.
Definition repo.h:2969
char const * user
User name for the branch.
Definition repo.h:2948
char const * name
The name of the branch.
Definition repo.h:2943
char const * comment
Optional comment (may be NULL).
Definition repo.h:2954
fsl_id_t basisRid
The checkin RID from which the branch should originate.
Definition repo.h:2939
char const * bgColor
Optional background color for the fossil(1) HTML timeline view.
Definition repo.h:2960
A general-purpose buffer class, analog to Fossil's Blob class, but it is not called fsl_blob to avoid...
Definition util.h:684
A list of fsl_card_F objects.
Definition repo.h:207
fsl_card_F * list
The list of F-cards.
Definition repo.h:212
uint32_t used
The number of entries in this->list which are in use.
Definition repo.h:216
uint32_t capacity
The number of entries currently allocated in this->list.
Definition repo.h:220
int32_t cursor
An internal cursor into this->list, used primarily for properly traversing the file list in delta man...
Definition repo.h:230
uint32_t flags
Internal flags.
Definition repo.h:234
F-cards each represent one file entry in a Manifest Artifact (i.e., a checkin version).
Definition repo.h:2200
char * priorName
Previous name if the file was renamed, else NULL.
Definition repo.h:2213
fsl_uuid_str uuid
UUID of the underlying blob record for the file.
Definition repo.h:2205
char * name
Name of the file.
Definition repo.h:2209
fsl_fileperm_e perm
File permissions.
Definition repo.h:2221
bool deckOwnsStrings
An internal optimization.
Definition repo.h:2232
Represents a J card in a Ticket Control Artifact.
Definition repo.h:2251
unsigned char flags
For internal use only.
Definition repo.h:2260
char * field
The ticket field to update.
Definition repo.h:2264
char * value
The value for the field.
Definition repo.h:2268
bool append
If true, the new value should be appended to any existing one with the same key, else it will replace...
Definition repo.h:2256
Represents a Q card in a Manifest or Control Artifact.
Definition repo.h:2320
fsl_cherrypick_type_e type
0==invalid, negative==backed out, positive=cherrypicked.
Definition repo.h:2322
fsl_uuid_str baseline
UUID of the baseline for the cherrypick.
Definition repo.h:2332
fsl_uuid_str target
UUID of the target of the cherrypick.
Definition repo.h:2327
Represents a tag in a Manifest or Control Artifact.
Definition repo.h:2278
fsl_uuid_str uuid
UUID of the artifact this tag is tagging.
Definition repo.h:2288
fsl_tagtype_e type
The type of tag.
Definition repo.h:2282
char * value
The tag's value.
Definition repo.h:2297
char * name
The tag's name.
Definition repo.h:2292
Parameters for fsl_checkin_commit().
Definition checkout.h:1074
Options for use with fsl_cidiff().
Definition repo.h:3942
fsl_cidiff_f callback
Callback to call on each iteration step.
Definition repo.h:3955
fsl_id_t v2
Checkin version (RID) for "version 2".
Definition repo.h:3951
fsl_id_t v1
Checkin version (RID) for "version 1".
Definition repo.h:3946
void * callbackState
Opaque state for the callback.
Definition repo.h:3960
Holds the state for a single iteration step of fsl_cidiff.
Definition repo.h:4041
fsl_cx * f
The associated fsl_cx instance.
Definition repo.h:4045
fsl_card_F const * fc2
The file, if any, corresponding to this->v2.
Definition repo.h:4084
fsl_deck const * d2
The deck corresponding to this->opt->v2.
Definition repo.h:4097
fsl_deck const * d1
The deck corresponding to this->opt->v1.
Definition repo.h:4092
int changes
Describes the change(s) being reported by the current iteration step, as a bitmask of fsl_cidiff_e va...
Definition repo.h:4074
int stepType
Denotes the type of this step in the iteration.
Definition repo.h:4069
fsl_cidiff_opt const * opt
The options object passed to fsl_cidiff().
Definition repo.h:4049
fsl_card_F const * fc1
The file, if any, corresponding to this->v1.
Definition repo.h:4079
The main Fossil "context" type.
Definition internal.h:400
A "deck" stores (predictably enough) a collection of "cards." Cards are constructs embedded within Fo...
Definition repo.h:319
struct fsl_deck::@350042316264271363175306321043117241313047322251 A
The 'A' (attachment) card.
fsl_uuid_str G
UUID for the 'G' (forum thread-root) card.
Definition repo.h:423
fsl_card_F_list F
The 'F' (file) card container.
Definition repo.h:418
char * U
The U (user) card.
Definition repo.h:493
char * tgt
Name of wiki page, or UUID of ticket or event (technote), to which the attachment applies.
Definition repo.h:363
void const * allocStamp
A marker which tells fsl_deck_finalize() whether or not fsl_deck_malloc() allocated this instance (in...
Definition repo.h:523
fsl_uuid_str src
UUID of the file being attached via the A-card.
Definition repo.h:368
char * name
Filename of the A-card.
Definition repo.h:357
char * H
The H (forum title) card.
Definition repo.h:428
char * L
The 'L' (wiki name/title) card.
Definition repo.h:451
fsl_id_t rid
DB repo.blob.rid value.
Definition repo.h:332
fsl_uuid_str uuid
The 'B' (baseline) card holds the UUID of baseline manifest.
Definition repo.h:377
fsl_buffer W
The W (wiki content) card.
Definition repo.h:498
fsl_uuid_str K
UUID for the 'K' (ticket) card.
Definition repo.h:446
fsl_list Q
'Q' (cherry pick) cards.
Definition repo.h:475
fsl_list M
List of UUIDs (fsl_uuid_str) in a cluster ('M' cards).
Definition repo.h:456
char * N
The 'N' (comment mime type) card.
Definition repo.h:464
fsl_list J
The 'J' card specifies changes to "value" of "fields" in tickets (FSL_SATYPE_TICKET).
Definition repo.h:441
fsl_satype_e type
Specifies the the type (or eventual type) of this artifact.
Definition repo.h:327
fsl_list T
List of 'T' (tag) cards.
Definition repo.h:488
struct fsl_deck::@135213207116306320240312043263123243330063044176 B
fsl_list P
List of UUIDs of parents ('P' cards).
Definition repo.h:470
double D
The 'D' (date) card, in Julian format.
Definition repo.h:398
char * C
The 'C' (comment) card.
Definition repo.h:393
fsl_cx * f
The Fossil context responsible for this deck.
Definition repo.h:346
fsl_deck * baseline
Baseline manifest corresponding to this->B.
Definition repo.h:388
fsl_deck * next
To potentially be used for a manifest cache.
Definition repo.h:515
char * R
The R-card holds an MD5 hash which is calculated based on the names, sizes, and contents of the files...
Definition repo.h:483
double julian
The 'E' card's date in Julian Day format.
Definition repo.h:407
fsl_uuid_str I
UUID for the 'I' (forum in-response-to) card.
Definition repo.h:433
fsl_buffer content
This is part of an optimization used when parsing fsl_deck instances from source text.
Definition repo.h:510
Generic list container type.
Definition util.h:156
fsl_size_t sizes[FSL_SATYPE_count]
The accumulated sizes of each blob type seen during rebuild.
Definition repo.h:3723
fsl_size_t phantomCount
The number of phantom artifacts seen during rebuild.
Definition repo.h:3713
fsl_size_t counts[FSL_SATYPE_count]
Counts of each blob type seen during rebuild.
Definition repo.h:3718
Options for the rebuild process.
Definition repo.h:3829
bool createClusters
True if clusters should be created.
Definition repo.h:3841
bool dryRun
If true, the transaction started by the rebuild process will end in a rollback even on success.
Definition repo.h:3848
bool randomize
Scan artifacts in a random order (generally only of use in testing the library's code).
Definition repo.h:3835
State for use with the fsl_rebuild_f() callback type.
Definition repo.h:3736
fsl_satype_e artifactType
Set to FSL_SATYPE_INVALID if the just-processed blob is not a fossil artifact, else false.
Definition repo.h:3780
fsl_rebuild_metrics metrics
Metrics from the rebuild.
Definition repo.h:3792
int errCode
This is only non-0 for FSL_MSG_REBUILD_DONE messages, in which case it holds the result code of the o...
Definition repo.h:3786
fsl_rebuild_opt const * opt
The options object used for this invocation of fsl_repo_rebuild().
Definition repo.h:3744
fsl_cx * f
Fossil context for which this rebuild is being performed.
Definition repo.h:3740
fsl_int_t blobSize
The size of the just-processed blob, -1 if it is a phantom blob, or 0 when this object is part of a F...
Definition repo.h:3773
fsl_size_t artifactCount
An approximate upper bound on the number of files fsl_repo_rebuild() will process.
Definition repo.h:3752
fsl_id_t rid
The blob.rid value of the just-processed blob.
Definition repo.h:3766
fsl_size_t stepNumber
One-based counter of total artifacts processed so far.
Definition repo.h:3760
Configuration parameters for fsl_repo_create().
Definition repo.h:4167
bool elideProjectCode
If true, the new repo will not have a "project-code" config entry.
Definition repo.h:4231
char const * commitMessage
The comment text used for the initial commit.
Definition repo.h:4191
bool allowOverwrite
If false, fsl_repo_create() will fail if this->filename already exists.
Definition repo.h:4224
char const * commitMessageMimetype
Mime type for the commit message (manifest N-card).
Definition repo.h:4203
char const * configRepo
If not NULL and not empty, fsl_repo_create() will use this repository database to copy the configurat...
Definition repo.h:4218
char const * username
Fossil user name for the admin user in the new repo.
Definition repo.h:4178
char const * filename
The file name for the new repository.
Definition repo.h:4171
Options for use with fsl_repo_extract().
Definition repo.h:2617
void * callbackState
Optional state pointer to pass to the callback when extracting.
Definition repo.h:2632
bool extractContent
If true, the fsl_repo_extract_state::content pointer passed to the callback will be non-NULL and will...
Definition repo.h:2641
fsl_id_t checkinRid
The version of the repostitory to check out.
Definition repo.h:2622
fsl_repo_extract_f callback
The callback to call for each extracted file in the checkin.
Definition repo.h:2627
Callback state for use with fsl_repo_extract_f() implementations to stream a given version of a repos...
Definition repo.h:2509
fsl_buffer const * content
If the fsl_repo_extract_opt object which was used to initiate the current extraction has the extractC...
Definition repo.h:2562
fsl_card_F const * fCard
The F-card being iterated over.
Definition repo.h:2550
fsl_id_t fileRid
File-level blob.rid for fc.
Definition repo.h:2524
void * callbackState
Client state passed to fsl_repo_extract().
Definition repo.h:2529
uint32_t fileCount
Total number of files to extract.
Definition repo.h:2572
uint32_t fileNumber
The current file number, starting at 1.
Definition repo.h:2570
struct fsl_repo_extract_state::@335110352153300217200340311252103177272306353261 count
These counters can be used by an extraction callback to calculate a progress percentage.
fsl_cx * f
The associated Fossil context.
Definition repo.h:2513
fsl_id_t checkinRid
RID of the checkin version for this file.
Definition repo.h:2519
Models user permissions precisely as fossil(1) does.
Definition repo.h:4367
bool readWiki
Definition repo.h:4375
bool adminForum
Definition repo.h:4395
bool moderateForum
Definition repo.h:4394
bool emailAlert
Definition repo.h:4396
bool ticketReport
Definition repo.h:4386
bool moderateTicket
Definition repo.h:4384
bool xReader
Definition repo.h:4402
bool readForum
Definition repo.h:4391
bool trustedForum
Definition repo.h:4393
bool appendWiki
Definition repo.h:4377
bool appendTicket
Definition repo.h:4382
bool xDeveloper
Definition repo.h:4403
bool writeUnversioned
Definition repo.h:4390
bool chat
Definition repo.h:4398
bool write
Definition repo.h:4371
bool setup
Definition repo.h:4368
bool announce
Definition repo.h:4397
bool privateContent
Definition repo.h:4389
bool debug
Definition repo.h:4399
bool writeWiki
Definition repo.h:4378
bool readAddr
Definition repo.h:4387
bool hyperlink
Definition repo.h:4373
bool zip
Definition repo.h:4388
bool writeTicket
Definition repo.h:4383
bool password
Definition repo.h:4370
bool readTicket
Definition repo.h:4380
bool admin
Definition repo.h:4369
bool clone
Definition repo.h:4374
bool moderateWiki
Definition repo.h:4379
bool writeForum
Definition repo.h:4392
bool read
Definition repo.h:4372
bool attach
Definition repo.h:4385
bool newTicket
Definition repo.h:4381
bool newWiki
Definition repo.h:4376
A list of fsl_xlinker instances.
Definition repo.h:1755
fsl_xlinker * list
Array of this->used elements.
Definition repo.h:1761
fsl_size_t capacity
Number of slots allocated in this->list.
Definition repo.h:1759
fsl_size_t used
Number of used items in this->list.
Definition repo.h:1757
A type for holding state for artifact crosslinking callbacks.
Definition repo.h:1731
fsl_deck_xlink_f f
Callback function.
Definition repo.h:1739
void * state
State for this->f's last argument.
Definition repo.h:1741
char const * name
Human-readable name of the crosslinker, noting that each registered crosslinker must have a unique na...
Definition repo.h:1737
char * fsl_uuid_str
fsl_uuid_str and fsl_uuid_cstr are "for documentation andreadability purposes" typedefs used to denot...
Definition util.h:72
char const * fsl_uuid_cstr
The const counterpart of fsl_uuid_str.
Definition util.h:80
int(* fsl_output_f)(void *state, void const *src, fsl_size_t n)
Generic interface for streaming out data.
Definition util.h:292