libfossil
fossil-content.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(NET_FOSSIL_SCM_FSL_CONTENT_H_INCLUDED)
4 #define NET_FOSSIL_SCM_FSL_CONTENT_H_INCLUDED
5 /*
6  Copyright (c) 2013 D. Richard Hipp
7 
8  This program is free software; you can redistribute it and/or
9  modify it under the terms of the Simplified BSD License (also
10  known as the "2-Clause License" or "FreeBSD License".)
11 
12  This program is distributed in the hope that it will be useful,
13  but without any warranty; without even the implied warranty of
14  merchantability or fitness for a particular purpose.
15 
16  Author contact information:
17  drh@hwaci.com
18  http://www.hwaci.com/drh/
19 
20  ******************************************************************************
21  This file declares public APIs for working with fossil-managed content.
22 */
23 
24 #include "fossil-db.h" /* MUST come first b/c of config macros */
25 
26 #if defined(__cplusplus)
27 extern "C" {
28 #endif
29 typedef struct fsl_card_F fsl_card_F;
30 typedef struct fsl_card_J fsl_card_J;
31 typedef struct fsl_card_Q fsl_card_Q;
32 typedef struct fsl_card_T fsl_card_T;
34 typedef struct fsl_deck fsl_deck;
35 
36 /**
37  This function is a programmatic interpretation of
38  this table:
39 
40  http://fossil-scm.org/index.html/doc/trunk/www/fileformat.wiki#summary
41 
42  For a given control artifact type and a card name in the form of
43  the card name's letter (e.g. 'A', 'W', ...), this function
44  returns 0 (false) if that card type is not permitted in this
45  control artifact type, a negative value if the card is optional
46  for this artifact type, and a positive value if the card type is
47  required for this artifact type.
48 
49  As a special case, if t==FSL_CATYPE_ANY then this function
50  always returns a negative value as long as card is a valid card
51  letter.
52 
53  Another special case: when t==FSL_CATYPE_CHECKIN and card=='F',
54  this returns a negative value because the table linked to above
55  says F-cards are optional. In practice we have yet to find a use
56  for checkins with no F-cards, so this library currently requires
57  F-cards at checkin-time even though this function reports that
58  they are optional.
59 */
60 FSL_EXPORT int fsl_card_is_legal( fsl_catype_t t, char card );
61 
62 /**
63  Artifact tag types used by the Fossil framework. Their values
64  are a hard-coded part of the Fossil format, and not subject to
65  change (only extension, possibly).
66 */
68 /**
69  Sentinel value for use with constructors/initializers.
70 */
72 /**
73  The "cancel tag" indicator, a.k.a. an anti-tag.
74 */
76 /**
77  The "add tag" indicator, a.k.a. a singleton tag.
78 */
80 /**
81  The "propagating tag" indicator.
82 */
84 };
86 
87 /**
88  Hard-coded IDs used by the 'tag' table of repository DBs. These
89  values get installed as part of the base Fossil db schema in new
90  repos, and they must never change.
91 */
93 /**
94  DB string tagname='bgcolor'.
95 */
97 /**
98  DB: tag.tagname='comment'.
99 */
101 /**
102  DB: tag.tagname='user'.
103 */
105 /**
106  DB: tag.tagname='date'.
107 */
109 /**
110  DB: tag.tagname='hidden'.
111 */
113 /**
114  DB: tag.tagname='private'.
115 */
117 /**
118  DB: tag.tagname='cluster'.
119 */
121 /**
122  DB: tag.tagname='branch'.
123 */
125 /**
126  DB: tag.tagname='closed'.
127 */
129 /**
130  DB: tag.tagname='parent'.
131 */
133 
134 /**
135  Largest tag ID reserved for internal use.
136 */
138 };
139 
140 /**
141  Returns one of '-', '+', or '*' for a valid input parameter, 0
142  for any other value.
143 */
144 FSL_EXPORT char fsl_tag_prefix_char( fsl_tag_type t );
145 
146 /**
147  A "deck" stores (predictably enough) a collection of "cards."
148  Cards are constructs embedded within Fossil's Control Artifacts
149  to denote various sorts of changes in a Fossil repository, and a
150  Deck encapsulates the cards for a single Control Artifact of an
151  arbitrary type, e.g. Manifest (a.k.a. "checkin") or Cluster. A
152  card is basically a command with a single-letter name and a
153  well-defined signature for its arguments. Each card is
154  represented by a member of this struct whose name is the same as
155  the card type (e.g. fsl_card::C holds a C-card and fsl_card::F
156  holds a list of F-card). Each type of artifact only allows
157  certain types of card. The complete list of valid card/construct
158  combinations can be found here:
159 
160  http://fossil-scm.org/index.html/doc/trunk/www/fileformat.wiki#summary
161 
162  fsl_card_is_legal() can be used determine if a given card type
163  is legal (per the above chart) with a given Control Artifiact
164  type (as stored in the fsl_deck::type member).
165 
166  The type member is used by some algorithms to determine which
167  operations are legal on a given Control Artifact type, so that
168  they can fail long before the user gets a chance to add a
169  malformed Control Artifact to the database. Clients who bypass
170  the fsl_deck APIs and manipulate the deck's members "by hand"
171  (so to say) effectively invoke undefined behaviour.
172 
173  The various routines to add/set cards in the deck are named
174  fsl_deck_CARDNAME_add() resp. fsl_deck_CARDNAME_set(). The "add"
175  functions represent cards which may appear multiple times
176  (e.g. the 'F' card) or have multiple values (the 'P' card), and
177  those named "set" represent unique or optional cards. The R-card
178  is the outlier, with fsl_deck_R_calc(). NEVER EVER EVER directly
179  modify a member of this struct - always use the APIs. The
180  library performs some optimizations which can lead to corrupt
181  memory and invalid free()s if certain members' values are
182  directly replaced by the client (as opposed to via the APIs).
183 
184  Note that the 'Z' card is not in this structure because it is a
185  hash of the other inputs and is calculated incrementally and
186  appended automatically by fsl_deck_output(). Adding the Z card
187  to this class would require that fsl_deck_output() and friends
188  take a non-const deck object (because Z is calculated
189  incrementally during output of the artifact), which just seems
190  philosophically wrong for an output operation. It might be
191  useful to expand fsl_deck_output() to write the Z card's result
192  to an optional output parameter.
193 
194  Maintenance reminder: please keep the card members alpha sorted to
195  simplify eyeball-searching through their docs.
196 
197  @see fsl_deck_malloc()
198  @see fsl_deck_init()
199  @see fsl_deck_parse()
200  @see fsl_deck_load_rid()
201  @see fsl_deck_finalize()
202  @see fsl_deck_clean()
203  @see fsl_deck_save()
204  @see fsl_deck_A_set()
205  @see fsl_deck_B_set()
206  @see fsl_deck_D_set()
207  @see fsl_deck_E_set()
208  @see fsl_deck_F_add()
209  @see fsl_deck_J_add()
210  @see fsl_deck_K_set()
211  @see fsl_deck_L_set()
212  @see fsl_deck_M_add()
213  @see fsl_deck_N_set()
214  @see fsl_deck_P_add()
215  @see fsl_deck_Q_add()
216  @see fsl_deck_R_set()
217  @see fsl_deck_T_add()
218  @see fsl_deck_U_set()
219  @see fsl_deck_W_set()
220 */
221 struct fsl_deck {
222  /**
223  Specifies the the type (or eventual type) of this
224  artifact. The function fsl_card_is_legal() can be used to
225  determined if a given card type is legal for a given value of
226  this member. APIs which add/set cards use that to determine if
227  the operation requested by the client is semantically legal.
228  */
230 
231  /**
232  DB repo.blob.rid value. Normally set by fsl_deck_parse().
233  */
235 
236  /**
237  Gets set by fsl_deck_parse() to the hash/UUID of the
238  manifest it parsed. Normally set by fsl_deck_parse().
239  */
241 
242  /**
243  The Fossil context responsible for this deck. We store this so
244  that some API routines to not require the caller to explicitly
245  pass around the context. Relatively few deck operations make
246  use of this.
247  */
249 
250  /**
251  The 'A' (attachment) card. Only used by FSL_CATYPE_ATTACHMENT
252  decks. The spec currently specifies only 1 A-card per
253  manifest, but conceptually this could/should be a list.
254  */
255  struct {
256  /**
257  Filename of the A-card.
258  */
259  char * name;
260 
261  /**
262  Name of event or UUID of ticket or wiki page to which the
263  attachment applies. For tickets/events, the "name" is its
264  UUID.
265  */
266  char * tgt;
267 
268  /**
269  UUID of the file being attached via the A-card.
270  */
272  } A;
273 
274  struct {
275  /**
276  The 'B' (baseline) card holds the UUID of baseline manifest.
277  This is empty for baseline manifests and holds the UUID of
278  the parent for delta manifests.
279  */
281 
282  /**
283  Baseline manifest corresponding to this->B. It is loaded on
284  demand by routines which need it, typically by calling
285  fsl_deck_F_rewind() (unintuitively enough!). The
286  parent/child relationship in Fossil is the reverse of
287  conventional - children own their parents, not the other way
288  around. i.e. this->baseline will get cleaned up
289  (recursively) when this instance is cleaned up (when the
290  containing deck is cleaned up).
291  */
293  } B;
294  /**
295  The 'C' (comment) card.
296  */
297  char * C;
298 
299  /**
300  The 'D' (date) card, in Julian format.
301  */
303 
304  /**
305  The 'E' (event) card.
306  */
307  struct {
308  /**
309  The 'E' card's date in Julian Day format.
310  */
312 
313  /**
314  The 'E' card's UUID.
315  */
317  } E;
318 
319  /**
320  The 'F' (file) card container.
321  */
322  struct {
323  /**
324  A list of 'F' (file) cards. Contains (fsl_card_F*)
325  entries.
326  */
328  /**
329  An internal cursor into this->list, used primarily for
330  properly traversing the file list in delta manifests.
331 
332  Maintenance note: internal updates to this member are the
333  only reason some of the deck APIs require a non-const deck.
334  */
336  } F;
337 
338  /**
339  The 'J' card specifies changes to "value" of "fields" in
340  tickets (FSL_CATYPE_TICKET).
341 
342  Holds (fsl_card_J*) entries.
343  */
345 
346  /**
347  The 'L' (wiki name/title) card.
348  */
349  char * L;
350 
351  /**
352  UUID for the 'K' (ticket) card.
353  */
355 
356  /**
357  List of UUIDs (fsl_uuid_str) in a cluster ('M' cards).
358  */
360 
361  /**
362  The 'N' (content mime type) card.
363  */
364  char * N;
365 
366  /**
367  List of UUIDs of parents ('P' cards). Entries are of type
368  (fsl_uuid_str).
369  */
371 
372  /**
373  'Q' (cherry pick) cards. Holds (fsl_card_Q*) entries.
374  */
376 
377  /**
378  The R-card holds an MD5 hash which is calculated based on the
379  names, sizes, and contents of the files included in a
380  manifest. See the class-level docs for a link to a page which
381  describes how this is calculated.
382  */
383  char * R;
384 
385  /**
386  List of 'T' (tag) cards. Holds (fsl_card_T*) instances.
387  */
389 
390  /**
391  The U (user) card.
392  */
393  char * U;
394 
395  /**
396  The W (wiki content) card.
397  */
399 
400  /**
401  For propagating error state through certain parts of the API.
402  */
404 
405  /**
406  This is part of an optimization used when parsing fsl_deck
407  instances from source text. For most types of card we re-use
408  string values in the raw source text rather than duplicate
409  them, and that requires storing the original text (as passed to
410  fsl_deck_parse()). This requires that clients never tinker
411  directly with values in a fsl_deck, in particular never assign
412  over them or assume they know who allocate the memory for that
413  bit.
414  */
416 
417  /**
418  To be used for a manifest cache.
419  */
421 
422  /**
423  A marker which tells fsl_deck_finalize() whether or not
424  fsl_deck_malloc() allocated this instance (in which case
425  fsl_deck_finalize() will fsl_free() it) or not (in which case
426  it does not fsl_free() it).
427  */
428  void const * allocStamp;
429 
430 };
431 
432 /**
433  Initialized-with-defaults fsl_deck structure, intended for copy
434  initialization.
435 */
437 
438 /**
439  Initialized-with-defaults fsl_deck structure, intended for
440  in-struct and const copy initialization.
441 */
442 #define fsl_deck_empty_m { \
443  FSL_CATYPE_ANY /*type*/, \
444  -1/*rid*/, \
445  NULL/*uuid*/, \
446  NULL/*f*/, \
447  {/*A*/ NULL /* name */, \
448  NULL /* tgt */, \
449  NULL /* src */}, \
450  {/*B*/ NULL /*uuid*/, \
451  NULL /*baseline*/}, \
452  NULL /* C */, \
453  0.0 /*D*/, \
454  {/*E*/ 0.0 /* julian */, \
455  NULL /* uuid */}, \
456  {/*F*/ fsl_list_empty_m /*list*/,0/*cursor*/}, \
457  fsl_list_empty_m /* J */, \
458  NULL /* L */, \
459  NULL /* K */, \
460  fsl_list_empty_m /* M */, \
461  NULL /* N */, \
462  fsl_list_empty_m /* P */, \
463  fsl_list_empty_m /* Q */, \
464  NULL /* R */, \
465  fsl_list_empty_m /* T */, \
466  NULL /* U */, \
467  fsl_buffer_empty_m /* W */, \
468  fsl_error_empty_m /* error */, \
469  fsl_buffer_empty_m/*content*/, \
470  NULL/*next*/, \
471  NULL/*allocStamp*/ \
472  }
473 
474 
475 /**
476  Allocates a new fsl_deck instance. Returns NULL on allocation
477  error. The returned value must eventually be passed to
478  fsl_deck_finalize() to free its resources.
479 
480  @see fsl_deck_finalize()
481  @see fsl_deck_clean()
482 */
484 
485 /**
486  Frees all resources belonging to the given deck's members
487  (including its parents, recursively), and wipes deck clean, but
488  does not free() deck. Is a no-op if deck is NULL. As a special
489  case, the (allocStamp, f) members of deck are kept intact.
490 
491  @see fsl_deck_finalize()
492  @see fsl_deck_malloc()
493 */
495 
496 /**
497  Frees all memory owned by deck (see fsl_deck_clean()). If deck
498  was allocated using fsl_deck_malloc() then this function
499  fsl_free()'s it, otherwise it does not free it.
500 
501  @see fsl_deck_malloc()
502  @see fsl_deck_clean()
503 */
505 
506 /**
507  Sets the A-card for an Attachment (FSL_CATYPE_ATTACHMENT)
508  deck. Returns 0 on success.
509 
510  Returns FSL_RC_MISUSE if any of (mf, filename, target) are NULL,
511  FSL_RC_RANGE if !*filename or if uuidSrc is not NULL and
512  fsl_is_uuid(uuidSrc) returns false.
513 
514  Returns FSL_RC_TYPE if mf is not (as determined by its mf->type
515  member) of a deck type capable of holding 'A' cards. (Only decks
516  of type FSL_CATYPE_ATTACHMENT may hold an 'A' card.) If uuidSrc
517  is NULL or starts with a NUL byte then it is ignored, otherwise
518  the same restrictions apply to it as to target.
519 
520  The target parameter represents the "name" of the
521  wiki/ticket/event record to which the attachment applies. For
522  wiki pages this is their normal name (e.g. "MyWikiPage"). For
523  events and tickets it is their full 40-byte UUID.
524 
525  uuidSrc is the UUID of the attachment blob itself. If it is NULL
526  or empty then this card indicates that the attachment will be
527  "deleted" (insofar as anything is ever deleted in Fossil).
528 */
529 FSL_EXPORT int fsl_deck_A_set( fsl_deck * mf, char const * filename,
530  char const * target, fsl_uuid_cstr uuidSrc);
531 
532 /**
533  Sets or unsets (if uuidBaseline is NULL or empty) the B-card for
534  the given manifest. Returns 0 on success, FSL_RC_MISUSE if !mf,
535  FSL_RC_OOM on allocation error. Setting this will delete any
536  prior values in mf->B, including a previously loaded
537  mf->B.baseline.
538 
539  Returns FSL_RC_RANGE if uuidBaseline is not NULL or exactly
540  FSL_UUID_STRLEN bytes. If it is NULL the current value is
541  freed.
542 
543  Returns FSL_RC_TYPE if mf is not syntactically allowed to have
544  this card card (as determined by
545  fsl_card_is_legal(mf->type,...)) or if the value is not a
546  syntactically valid UUID.
547 */
548 FSL_EXPORT int fsl_deck_B_set( fsl_deck * mf, fsl_uuid_cstr uuidBaseline);
549 
550 /**
551  Semantically identical to fsl_deck_B_set() but sets the C-card
552  and does not place a practical limit on the comment's length.
553  comment must be the comment text for the change being applied.
554 */
555 FSL_EXPORT int fsl_deck_C_set( fsl_deck * mf, char const * comment, fsl_int_t cardLen);
556 
557 /**
558  Sets mf's D-card as a Julian Date value. Returns FSL_RC_MISUSE
559  if !mf, FSL_RC_RANGE if date is negative, else 0. Has no
560  side-effects on error.
561 
562 */
564 
565 /**
566  Sets the E-card in the given deck. date may not be negative -
567  use fsl_db_julian_now() or fsl_julian_now() to get a default
568  time if needed. Retursn FSL_RC_MISUSE if !mf or !uuid,
569  FSL_RC_RANGE if date is not positive, FSL_RC_RANGE if uuid is
570  not a valid UUID string.
571 
572  Note that the UUID for an event, unlike most other UUIDs, need
573  not be calculated - it may be a random hex string, but it must
574  pass the fsl_is_uuid() test. Use fsl_db_random_hex() to generate
575  random UUIDs. When editing events, e.g. using the HTML UI, only
576  the most recent event with the same UUID is shown. So when
577  updating events, be sure to apply the same UUID to the edited
578  copies before saving them.
579 */
581 
582 /**
583  Adds a new F-card to the given deck. The uuid argument is
584  required to be NULL or pass the fsl_is_uuid() test. The name
585  must be a "simplified path name" (as determined by
586  fsl_is_simple_pathname()), or FSL_RC_RANGE is returned.
587 
588  perms should be one of the fsl_file_perm_t values (0 is the usual
589  case).
590 
591  oldName must only be non-NULL when renaming a file, and it must
592  follow the same naming rules as the name parameter.
593 
594  Returns 0 on success.
595 */
596 FSL_EXPORT int fsl_deck_F_add( fsl_deck * mf, char const * name,
597  fsl_uuid_cstr uuid,
598  fsl_file_perm_t perm,
599  char const * oldName);
600 
601 /**
602  Adds the given file instance to the given deck. Returns 0 on
603  success, FSL_RC_MISUSE if either argument is NULL, FSL_RC_OOM if
604  appending the file to the list fails.
605 
606  On success ownership of t is passed to mf. On error ownership is
607  not modified.
608 */
610 
611 /**
612  Callback type for use with fsl_deck_F_foreach() and
613  friends. Implementations must return 0 on success, FSL_RC_BREAK
614  to abort looping without an error, and any other value on error.
615 */
616 typedef int (*fsl_card_F_visitor_f)(fsl_card_F const * fc,
617  void * state);
618 
619 /**
620  For each F-card in d, cb(card,visitorState) is called. Returns
621  the result of that loop. If cb returns FSL_RC_BREAK, the
622  visitation loop stops immediately and this function returns
623  0. If cb returns any other non-0 code, looping stops and that
624  code is returned immediately.
625 
626  If includeBaseline is false or d has no baseline (i.e. it is not a
627  delta manifest) then this will visit all the F-cards. If
628  includeBaseline is false and and d is a delta manifest (i.e. it has
629  a baseline manifest) then only the F-cards appearing the delta
630  manifest are visited (this is not normally what clients need,
631  however). If d is a delta manifest then it iterates through the
632  F-cards such that d's copy of a given card takes precedence over
633  the baseline's version.
634 
635  If includeBaseline is true and d appears to have a baseline, but
636  it is not yet loaded, this function loads it.
637 
638  The F-cards will be visited in the order they are declared in
639  d. For loaded manifests this is always lexical order (for delta
640  manifests, consistent across the delta and baseline). For
641  hand-created decks which have not been fsl_deck_unshuffle()'d, the
642  order is unspecified.
643 
644  This function calls fsl_deck_F_rewind() if includeBaseline is
645  true, so the caller need not do so.
646 */
647 FSL_EXPORT int fsl_deck_F_foreach( fsl_deck * d, char includeBaseline,
648  fsl_card_F_visitor_f cb, void * visitorState );
649 
650 /**
651  Fetches the next F-card entry from d. fsl_deck_F_rewind() must
652  have be successfully executed one time before calling this, as
653  that routine ensures that the baseline is loaded (if needed),
654  which is needed for proper iteration over delta manifests.
655 
656  This routine always assigns *f to NULL before starting its work,
657  so the client can be assured that it will never contain the same
658  value as before calling this.
659 
660  On success 0 is returned and *f is assigned to the next F-card.
661  If *f is NULL when returning 0 then the end of the list has been
662  reached (fsl_deck_F_rewind() can be used to re-set it).
663 
664  Example usage:
665 
666  @code
667  int rc;
668  fsl_card_F const * fc = NULL;
669  rc = fsl_deck_F_rewind(d);
670  if(!rc) while( !(rc=fsl_deck_F_next(d, &fc)) && fc) {...}
671  @endcode
672 
673  Unfortunately there is some internal inconsistency in the
674  handling and traversal of "deleted" files. Delta manifests mark
675  them as an F-card with a NULL UUID. Baseline checkins do not
676  contain F-cards for deleted files. For most purposes deleted
677  entries can be skipped over, but it is sometimes interesting to
678  know about them. That said, because baseline manifests do not
679  explicitly record deletion entries, it is not trivial to figure
680  out if a given file was deleted between two baselines (it
681  requires traversing both of them in full). FIXME: There is
682  currently a case where this routine will _not_ return a deleted
683  file, though it does for other cases.
684 
685  Implementation notes: for baseline manifests this is a very
686  fast and simple operation. For delta manifests it gets
687  rather complicated.
688 
689  Bugs:
690 
691  - There are some inconsistencies in exactly when deleted
692  files are reported by this function. Some deleted entries
693  will get through and some won't. This is due to a change
694  in historical behaviour which "missed a spot."
695 */
696 FSL_EXPORT int fsl_deck_F_next( fsl_deck * d, fsl_card_F const **f );
697 
698 /**
699  Rewinds d's F-card traversal iterator and loads d's baseline
700  manifest, if it has one and it is not loaded already. Returns 0
701  on success. The only error condition is if loading of the
702  a baseline manifest fails.
703 */
705 
706 /**
707  Looks for a file in a manifest or (for a delta manifest) its
708  baseline. No normalization of the given filename is performed -
709  it is assumed to be relative to the root of the checkout.
710 
711  It requires that d->type be FSL_CATYPE_CHECKIN and that d be
712  loaded from a stored manifest or have been fsl_deck_unshuffle()'d
713  (if called on an under-construction deck). Specifically, this
714  routine requires that d->F be sorted properly or results are
715  undefined.
716 
717  If d->f is set then it is assumed to be the fsl_cx instance which
718  deck was loaded from. In that case this function takes on two new
719  behaviours:
720 
721  - The search take's d->f's underlying case-insensitive option into
722  account. i.e. if case-insensitivy is on then files in any case
723  will match.
724 
725  - If no match is found in d and is a delta manifest (d->B.uuid
726  is set) then d's baseline is lazily loaded (if needed) and
727  the search continues there. (Delta manifests are only one level
728  deep, so this is not recursive.)
729 
730  Returns NULL if !d, !d->f, or d->type!=FSL_CATYPE_CHECKIN, if no
731  entry is found, or if delayed loading of the parent manifest (if
732  needed) of a delta manifest fails (in which case d->f's error
733  state should hold more information about the problem).
734 
735  In debug builds this function asserts that d is not NULL.
736 
737  Design note: d "should" be const, but search optimizations for
738  the typical use case require potentially lazy-loading
739  d->B.baseline and updating d->F.
740 */
741 FSL_EXPORT fsl_card_F const * fsl_deck_F_search(fsl_deck *d, const char *zName);
742 
743 /**
744  Given two F-card instances, this function compares their names
745  (case-insensitively). Returns a negative value if lhs is
746  lexically less than rhs, a positive value if lhs is lexically
747  greater than rhs, and 0 if they are lexically equivalent (or are
748  the same pointer).
749 
750  Results are undefined if either argument is NULL.
751 */
752 FSL_EXPORT int fsl_card_F_compare( fsl_card_F const * lhs,
753  fsl_card_F const * rhs);
754 
755 /**
756  If fc->uuid refers to a blob in f's repository database then that
757  content is placed into dest (as per fsl_content_get()) and 0 is
758  returned. Returns FSL_RC_NOT_FOUND if fc->uuid is not
759  found. Returns FSL_RC_MISUSE if any argument is NULL. If
760  fc->uuid is NULL (indicating that it refers to a file deleted in
761  a delta manifest) then FSL_RC_RANGE is returned. Returns
762  FSL_RC_NOT_A_REPO if f has no repository opened.
763 
764  On any error but FSL_RC_MISUSE (basic argument validation) f's
765  error state is updated to describe the error.
766 
767  @see fsl_content_get()
768 */
769 FSL_EXPORT int fsl_card_F_content( fsl_cx * f, fsl_card_F const * fc,
770  fsl_buffer * dest );
771 
772 
773 /**
774  Adds a J-card to the given deck, setting/updating the given ticket
775  property key to the given value. The key is required but the value
776  is optional (may be NULL). If isAppend then the value is appended
777  to any existing value, otherwise it replaces any existing value.
778 
779  It is currently unclear whether it is legal to include multiple
780  J cards for the same key in the same control artifact, in
781  particular if their isAppend values differ.
782 
783  Returns 0 on success, FSL_RC_MISUSE if !mf or !key, FSL_RC_RANGE
784  if !*field, FSL_RC_TYPE if mf is of a type for which J cards are
785  not legal (see fsl_card_is_legal()), FSL_RC_OOM on allocation
786  error.
787 */
788 FSL_EXPORT int fsl_deck_J_add( fsl_deck * mf, char isAppend,
789  char const * key, char const * value );
790 
791 /**
792  Semantically identical fsl_deck_B_set() but sets the K-card. uuid
793  must be the UUID of the ticket this change is being applied to.
794 */
796 
797 /**
798  Semantically identical fsl_deck_B_set() but sets the L-card.
799  title must be the wiki page title text of the wiki page this
800  change is being applied to.
801 */
802 FSL_EXPORT int fsl_deck_L_set( fsl_deck * mf, char const *title, fsl_int_t len);
803 
804 /**
805  Adds the given UUID as an M-card entry. Returns 0 on success, or:
806 
807  FSL_RC_MISUSE if !mf or !uuid
808 
809  FSL_RC_TYPE if fsl_deck_check_type(mf,'M') returns false.
810 
811  FSL_RC_RANGE if !fsl_is_uuid(uuid).
812 
813  FSL_RC_OOM if memory allocation fails while adding the entry.
814 */
816 
817 /**
818  Semantically identical to fsl_deck_B_set() but sets the N card.
819  mimeType must be the content mime type for comment text of the
820  change being applied.
821 */
822 FSL_EXPORT int fsl_deck_N_set( fsl_deck * mf, char const *mimeType, fsl_int_t len);
823 
824 /**
825  Adds the given UUID as a parent of the given change record. If len
826  is less than 0 then fsl_strlen(parentUuid) is used to determine
827  its length. Returns FSL_RC_MISUE if !mf, !parentUuid, or
828  !*parentUuid. Returns FSL_RC_RANGE if parentUuid is not 40
829  bytes long.
830 
831  The first P-card added to a deck MUST be the UUID of its primary
832  parent (one which was not involved in a merge operation). All
833  others (from merges) are considered "non-primary."
834 
835 */
836 FSL_EXPORT int fsl_deck_P_add( fsl_deck * mf, fsl_uuid_cstr parentUuid);
837 
838 /**
839  If d contains a P card with the given index, this returns the
840  RID corresponding to the UUID at that index. Returns a negative
841  value on error, 0 if there is no for that index or the index
842  is out of bounds.
843 */
845 
846 /**
847  Adds a Q-card record to the given deck. The type argument must
848  be negative for a backed-out change, positive for a cherrypicked
849  change. target must be a valid UUID string. If baseline is not
850  NULL then it also must be a valid UUID.
851 
852  Returns 0 on success, non-0 on error. FSL_RC_MISUSE if !mf
853  or !target, FSL_RC_RANGE if target/baseline are not valid
854  UUID strings (baseline may be NULL).
855 */
856 FSL_EXPORT int fsl_deck_Q_add( fsl_deck * mf, int type,
857  fsl_uuid_cstr target,
858  fsl_uuid_cstr baseline );
859 
860 /**
861  Functionally identical to fsl_deck_B_set() except that it sets
862  the R-card. Returns 0 on succes, FSL_RC_RANGE if md5 is not NULL
863  or exactly FSL_MD5_STRLEN bytes long (not including trailing
864  NUL). If md5==NULL the current R value is cleared.
865 
866  It would be highly unusual to have to set the R-card manually,
867  as its calculation is quite intricate/intensive. See
868  fsl_deck_R_calc() and fsl_deck_unshuffle() for details
869 */
870 FSL_EXPORT int fsl_deck_R_set( fsl_deck * mf, char const *md5);
871 
872 /**
873  Adds a new T-card (tag) entry to the given deck.
874 
875  If uuid is not NULL and fsl_is_uuid(uuid) returns false then
876  this function returns FSL_RC_RANGE. If uuid is NULL then it is
877  assumed to be the UUID of the currently-being-constructed
878  artifact in which the tag is contained (which appears as the '*'
879  character in generated artifacts).
880 
881  Returns 0 on success. Returns FSL_RC_MISUE if !mf or
882  !name. Returns FSL_RC_TYPE (and update's mf's error state with a
883  message) if the T card is not legal for mf (see
884  fsl_card_is_legal()). Returns FSL_RC_RANGE if !*name, tagType
885  is invalid, or if uuid is not NULL and fsl_is_uuid(uuid)
886  return false. Returns FSL_RC_OOM if an allocation fails.
887 */
888 FSL_EXPORT int fsl_deck_T_add( fsl_deck * mf, fsl_tag_type tagType,
889  fsl_uuid_cstr uuid, char const * name,
890  char const * value);
891 
892 /**
893  Adds the given tag instance to the given manifest.
894  Returns 0 on success, FSL_RC_MISUSE if either argument
895  is NULL, FSL_RC_OOM if appending the tag to the list
896  fails.
897 
898  On success ownership of t is passed to mf. On error ownership is
899  not modified.
900 
901 */
903 
904 
905 /**
906  Calculates the value of d's R-card based on its F-cards and
907  updates d->R. It may also, as a side-effect, sort d->F.list
908  lexically (a requirement of a R-card calculation). Returns 0 on
909  success. This requires that d->f have an opened repository db.
910  If d has no F-cards then the R-card's value is that of the
911  initial MD5 hash state.
912 
913  Note that this calculation is exceedingly memory-hungry. While
914  Fossil originally required R-cards, the cost of calculation
915  eventually caused the R-card to be made optional. This API
916  allows the client to decide on whether to use them (for more
917  (admittedly redundant!) integrity checking) or not (must faster
918  but "not strictly historically correct"), but defaults to having
919  them enabled for symmetry with fossil(1).
920 */
922 
923 /**
924  Semantically identical fsl_deck_B_set() but sets the U-card.
925  userName must be the user who's name should be recorded for
926  this change.
927 */
928 FSL_EXPORT int fsl_deck_U_set( fsl_deck * mf, char const *userName, fsl_int_t len);
929 
930 /**
931  Semantically identical fsl_deck_B_set() but sets the W-card.
932  content must be the page content of the Wiki page or Event this
933  change is being applied to.
934 */
935 FSL_EXPORT int fsl_deck_W_set( fsl_deck * mf, char const *content, fsl_int_t len);
936 
937 /**
938  Must be called to initialize a newly-created/allocated deck
939  instance. This function clears out all contents of the d
940  parameter except for its (f, type, allocStamp) members, sets its
941  (f, type) members, and leaves d->allocStamp intact.
942 */
943 FSL_EXPORT void fsl_deck_init( fsl_cx * cx, fsl_deck * d, fsl_catype_t type );
944 
945 /**
946  Equivalent to fsl_deck_required_cards_check(d, NULL);
947 */
949 
950 /**
951  Returns true (non-0) if d contains data for all _required_
952  cards, as determined by the value of d->type, else returns false
953  (0). It returns 0 if d->type==FSL_CATYPE_ANY, as that is a
954  placeholder value intended to be re-set by the deck's user.
955 
956  The library calls this as needed, but clients may, if they want
957  to. Note, however, that for FSL_CATYPE_CHECKIN decks it may fail
958  if the deck has not been fsl_deck_unshuffle()d yet because the
959  R-card gets calculated there (if needed).
960 
961  Returns 0 if d is NULL, otherwise if it returns 0 and err is not
962  NULL then err will contain a description of the first missing
963  card. Assuming the caller has a non-const reference to d, it is
964  legal to pass &d->error as the second parameter.
965 
966  As a special case, if d->f is not NULL, d->f is configured to
967  calculate R-cards, d->type==FSL_CATYPE_CHECKIN AND d->R is not
968  set, this will fail (with a descriptive error message).
969 
970  Another special case: for FSL_CATYPE_CHECKIN decks, if no
971  F-cards are in th deck then an R-card is required to avoid a
972  potental (admittedly harmless) syntactic ambiguity with
973  FSL_CATYPE_CONTROL artifacts. The only legal R-card for a
974  checkin with no F-cards has the initial MD5 hash state value
975  (defined in the constant FSL_MD5_INITIAL_HASH), and that
976  precondition is checked in this routine. fsl_deck_unshuffle()
977  recognizes this case and adds the initial-state R-card, so
978  clients normally need not concern themselves with this. If d has
979  F-cards, whether or not an R-card is required depends on
980  conditions described above.
981 
982  Enough about the R-card. In all other cases not described above,
983  R-cards are not required (and they are only ever required on
984  FSL_CATYPE_CHECKIN manifests).
985 
986  Though fossil(1) does not technically require F-cards in
987  FSL_CATYPE_CHECKIN decks, so far none of the Fossil developers
988  have found a use for a checkin without F-cards except the
989  initial empty checkin. Additionally, a checkin without F-cards
990  is potentially syntactically ambiguous (it could be an EVENT or
991  ATTACHMENT artifact if it has no F- or R-card). So... this
992  library _normally_ requires that CHECKIN decks have at least one
993  F-card. This function, however, does not consider F-cards to be
994  strictly required.
995 */
997  fsl_error * err);
998 
999 
1000 /**
1001  Prepares the given deck for output by ensuring that cards
1002  which need to be sorted are sorted, and it may run some
1003  last-minute validation checks.
1004 
1005  The cards which get sorted are: F, J, M, Q, T. The P-card list
1006  is _not_ sorted - the client is responsible for ensuring that
1007  the primary parent is added to that list first, and after that
1008  the ordering is(?) largely irrelevant. It is not possible(?) for
1009  the library to determine a proper order for P-cards, nor to
1010  validate that order at input-time.
1011 
1012  If calculateRCard is true and fsl_card_is_legal(d,'R') then this
1013  function calculates the R-card for the deck. The R-card
1014  calculation is _extremely_ memory-hungry but adds another level
1015  of integrity checking to Fossil. If d->type is not
1016  FSL_CATYPE_MANIFEST then calculateRCard is ignored.
1017 
1018  If calculateRCard is false then the F-cards (if any) are sorted.
1019  If no F-cards are present AND d->type is FSL_CATYPE_CHECKIN then
1020  the R-card is set to the initial MD5 hash state (the only legal
1021  R-card value for an empty F-card list).
1022 
1023  The R-card, if used, must be calculated before
1024  fsl_deck_output()ing a deck containing F-cards. Clients may
1025  alternately call fsl_deck_R_calc() to calculate the R card
1026  separately, but there is little reason to do so. There are rare
1027  cases where the client can call fsl_deck_R_set()
1028  legally. Historically speaking the R-card was required when
1029  F-cards were used, but it was eventually made optional because
1030  (A) the memory cost and (B) it's part of a 3rd or 4th level of
1031  integrity-related checks, and is somewhat superfluous.
1032 
1033  @see fsl_deck_output()
1034  @see fsl_deck_save()
1035 */
1036 FSL_EXPORT int fsl_deck_unshuffle( fsl_deck * d, char calculateRCard );
1037 
1038 /**
1039  Renders the given control artifact's contents to the given output
1040  function and calculates any cards which cannot be calculated until
1041  the contents are complete (namely the Z-card).
1042 
1043  fsl_deck_unshuffle() must have been called on the deck first to
1044  do any required sorting and to finalize any pending values which
1045  need to be calculated for the deck (namely the R-card).
1046 
1047  Returns 0 on success, FSL_RC_MISUSE if !mf or !f. If out()
1048  returns non-0, output stops and that code is
1049  returned. outputState is passed as the first argument to
1050  out(). out() may be called an arbitrary number of times by this
1051  routine.
1052 
1053  The errOut argument may be NULL. If it is not NULL then most
1054  types of errors will update errOut with information about the
1055  problem. Tip: this function cannot update mf->error because mf
1056  is const (because this is an output-only operation), but the
1057  client _may_ pass (&mf->error) as the 4th argument, assuming his
1058  own copy of mf is non-const.
1059 
1060  The exact structure of the ouput depends on the value of
1061  mf->type, and FSL_RC_TYPE is returned if this function cannot
1062  figure out what to do with the given cardset's type.
1063 
1064  Returns FSL_RC_CA_SYNTAX if fsl_deck_has_required_cards()
1065  returns false.
1066 
1067  @see fsl_deck_unshuffle()
1068  @see fsl_deck_save()
1069 */
1070 FSL_EXPORT int fsl_deck_output( fsl_deck const * mf,
1071  fsl_output_f out, void * outputState,
1072  fsl_error * errOut );
1073 
1074 
1075 /**
1076  Saves the given deck into f's repository database as new control
1077  artifact content. If isPrivate is true then the content is
1078  marked as private, otherwise it is not. Note that isPrivate is a
1079  suggestion and might be trumped by existing state within f or
1080  its repository, and such a trumping is not treated as an
1081  error. e.g. tags are automatically private when they tag private
1082  content.
1083 
1084  Before saving, the deck is passed through fsl_deck_unshuffle()
1085  and fsl_deck_output(), which will fail for a variety of
1086  easy-to-make errors such as the deck missing required cards.
1087  For unshuffle purposes, the R-card gets calculated if the deck
1088  has any F-cards AND if the caller has not already set/calculated
1089  it AND if f's FSL_CX_F_CALC_R_CARD flag is set (it is on by
1090  default for historical reasons, but this may change at some
1091  point).
1092 
1093  Returns 0 on success, the usual non-0 suspects on error.
1094 
1095  If d->rid and d->uuid are set when this is called, it is assumed
1096  that we are saving existing or phantom content, and in that
1097  case:
1098 
1099  - An existing phantom is populated with the new content.
1100 
1101  - If an existing record is found with a non-0 size then it is
1102  not modified but this is currently not treated as an error (for
1103  historical reasons, though one could argue that it should result
1104  in FSL_RC_ALREADY_EXISTS).
1105 
1106  ACHTUNG: the pre-existing blob case is as yet untested!
1107 
1108  If d->rid and d->uuid are not set when this is called then... on
1109  success, d->rid and d->uuid will contain the values held by
1110  their counterparts in the blob table. They will only be set on
1111  success because they would otherwise refer to db records which
1112  get destroyed when the transaction rolls back.
1113 
1114  After saving, the deck gets crosslinked (fsl_deck_crosslink())
1115  to update any relationships described by the deck.
1116 
1117  The save operation happens within a transaction, of course, and
1118  on any sort of error, db-side changes are rolled back. Note that
1119  it _is_ legal to start the transaction before calling this,
1120  which effectively makes this operation part of that transaction.
1121 
1122  Maintenance reminder: this function also does a small bit of
1123  artifact-type-specific processing.
1124 
1125  @see fsl_deck_output()
1126  @see fsl_content_put_ex()
1127 */
1128 FSL_EXPORT int fsl_deck_save( fsl_deck * d, char isPrivate );
1129 
1130 /**
1131  Runs postprocessing on the Control Artifact represented by
1132  d. d->f must be set, d->rid must be set and valid and d's
1133  contents must accurately represent the stored manifest for the
1134  given rid. This is normally run just after the insertion of a
1135  new manifest, but will (eventually) also be run as part of a
1136  rebuild.
1137 
1138  Returns FSL_RC_MISUSE if !f or !d, FSL_RC_RANGE if d->rid<=0,
1139  FSL_RC_MISUSE (with more error info in f) if d does not
1140  contain all required cards for its d->type value.
1141 
1142  Crosslinking of ticket artifacts is currently missing.
1143 
1144  Design note: d "really should" be const here but some internals
1145  (d->F.cursor and delayed baseline loading) currently prohibit
1146  it. In addition, we need d->f to be non-const.
1147 */
1148 FSL_EXPORT int fsl_deck_crosslink( fsl_deck /* const */ * d );
1149 
1150 /**
1151  Parses src as Control Artifact content and populates d with it.
1152 
1153  d will be cleaned up before parsing if it has any contents.
1154 
1155  This function _might_ take over the contents of the source
1156  buffer on success or it _might_ leave it for the caller to clean
1157  up or re-use, as he sees fit. If the caller does not intend to
1158  re-use the buffer, he should simply pass it to
1159  fsl_buffer_clear() after calling this (no need to check if it
1160  has contents or not first).
1161 
1162  When taking over the contents then on success, after returning
1163  src->mem will be NULL, and all other members will be reset to
1164  their default state. This function only takes over the contents
1165  if it decides to implement certain memory optimizations.
1166 
1167  Ownership of src itself is never changed by this function, only
1168  (possibly!) the ownership of its contents.
1169 
1170  In any case, the content of the source buffer is modified by
1171  this function because (A) that simplifies tokenization greatly,
1172  (B) saves us having to make another copy to work on, (C) the
1173  original implementation did it that way, (D) because in
1174  historical use the source is normally thrown away after parsing,
1175  anyway, and (E) in combination with taking ownership of src's
1176  contents it allows us to optimize away some memory allocations
1177  by re-using the internal memory of the buffer. This function
1178  never changes src's size, but it mutilates its contents
1179  (injecting NUL bytes as token delimiters).
1180 
1181  If d->type is _not_ FSL_CATYPE_ANY when this is called, then
1182  this function requires that the input to be of that type. We can
1183  fail relatively quickly in that case, and this can be used to
1184  save some downstream code some work. Note that the initial type
1185  for decks created using fsl_deck_malloc() or copy-initialized
1186  from ::fsl_deck_empty is FSL_CATYPE_ANY, so normally clients do
1187  not need to set this (unless they want to, as a small
1188  optimization).
1189 
1190  On success it returns 0 and d will be updated with the state
1191  from the input artifact. (Ideally, outputing d via
1192  fsl_deck_output() will produce a lossless copy of the original.)
1193  d->uuid will be set to the SHA1 of the input artifact, ignoring
1194  any surrounding PGP signature for hashing purposes.
1195 
1196  If d->f is not NULL, has an opened repository db, and the parsed
1197  artifact has a counterpart in the database (determined via an
1198  SHA1 match) then d->rid is set to the record ID.
1199 
1200  On error, if there is error information to propagate beyond the
1201  result code then it is stored in d->f (if that is not NULL),
1202  else in d->error. Whether or not such error info is propagated
1203  depends on the type of error, but anything more trivial than
1204  invalid arguments will be noted there.
1205 
1206  d might be partially populated on error, so regardless of success
1207  or failure, the client must eventually pass d to
1208  fsl_deck_finalize() to free its memory.
1209 
1210  Error result codes include:
1211 
1212  - FSL_RC_MISUSE if any pointer argument is NULL.
1213 
1214  - FSL_RC_CA_SYNTAX on syntax errors.
1215 
1216  - FSL_RC_CONSISTENCY if validation of a Z-card fails.
1217 
1218  - Any number of errors coming from the allocator, database, or
1219  fsl_deck APIs used here.
1220 */
1222 
1223 /**
1224  Loads the content from given rid and tries to parse it as a
1225  Fossil artifact. If rid==0 the current checkout (if opened) is
1226  used. (Trivia: there can never be a checkout with rid==0 but
1227  rid==0 is sometimes valid for an new/empty repo devoid of
1228  commits). If type==FSL_CATYPE_ANY then it will allow any type of
1229  control artifact, else it returns FSL_RC_TYPE if the loaded
1230  artifact is of the wrong type.
1231 
1232  Returns 0 on success.
1233 
1234  d may be partially populated on error, and the caller must
1235  eventually pass it to fsl_deck_finalize() resp. fsl_deck_clean()
1236  regardless of success or error. This function "could" clean it
1237  up on error, but leaving it partially populated makes debugging
1238  easier. If the error was an artifact type mismatch then d will
1239  "probably" be properly populated but will not hold the type of
1240  artifact requested. It "should" otherwise be well-formed because
1241  parsing errors occur before the type check can happen, but
1242  parsing of invalid manifests might also trigger a FSL_RC_TYPE
1243  error of a different nature. The morale of the storage is: if
1244  this function returns non-0, assume d is useless and needs to be
1245  cleaned up.
1246 
1247  f's error state may be updated on error (for anything more
1248  serious than basic argument validation errors).
1249 
1250  On success d->f is set to f.
1251 
1252  @see fsl_deck_load_sym()
1253 */
1255  fsl_id_t rid, fsl_catype_t type );
1256 
1257 /**
1258  A convenience form of fsl_deck_load_rid() which uses
1259  fsl_sym_to_rid() to convert symbolicName into an artifact RID.
1260  See fsl_deck_load_rid() for the symantics of the first, third,
1261  and fourth arguments, as well as the return value. See
1262  fsl_sym_to_rid() for the allowable values of symbolicName.
1263 
1264  @see fsl_deck_load_rid()
1265 */
1267  char const * symbolicName, fsl_catype_t type );
1268 
1269 /**
1270  Loads the baseline manifest specified in d->B.uuid. Returns 0 on
1271  success, if d->B.baseline is already set, or d->B.uuid is NULL
1272  (in which case there is no baseline).
1273 
1274  Neither argument may be NULL and d must be a fully-populated
1275  object, complete with a proper d->rid, before calling this.
1276 
1277  On success 0 is returned. If d->B.baseline is NULL then
1278  it means that d has no baseline manifest (and d->B.uuid will be NULL
1279  in that case). If d->B.baseline is not NULL then it is owned by
1280  d and will be cleaned up when d is cleaned/finalized.
1281 
1282  Error codes include, but are not limited to:
1283 
1284  - FSL_RC_MISUSE if !d or !d->f.
1285 
1286  - FSL_RC_NOT_A_REPO if f has no opened repo db.
1287 
1288  - FSL_RC_RANGE if d->rid<=0, but that might propagate up from
1289  a lower-level call as well.
1290 
1291  On non-trivial errors f's error state will be updated to hold
1292  a description of the problem.
1293 
1294  Some misuses trigger assertions in debug builds.
1295 
1296 */
1298 
1299 /**
1300  A callback interface for manifest crosslinking, so that we can
1301  farm out the updating of the event table. Each callback
1302  registered via fsl_xlink_listener() will be called at the end of
1303  the so-called crosslinking process, which is run every time a
1304  control artifact is processed for f's repository database,
1305  passed the fossil context, the deck being crosslinked, and the
1306  client-provided state which was registered with
1307  fsl_xlink_listener().
1308 
1309  Implementations must return 0 on success or some other fsl_rc_t
1310  value on error. Returning non-0 causes the database transaction
1311  for the crosslinking operation to roll back, effectively
1312  cancelling whatever pending operation triggered the
1313  crosslink. If any callback fails, processing stops immediately -
1314  no other callbacks are executed.
1315 
1316  Implementations which want to report more info than an integer
1317  should call fsl_cx_err_set() to set f's error state, as that
1318  will be propagated up to the code which initiated the failed
1319  crosslink.
1320 
1321  Potential TODO: we might need to make the deck parameter
1322  non-const so that clients can, e.g., use fsl_deck_F_rewind() and
1323  friends.
1324 
1325  @see fsl_xlink_listener()
1326 */
1327 typedef int (*fsl_deck_xlink_f)(fsl_cx * f, fsl_deck const * d, void * state);
1328 
1329 /**
1330  Adds the given function as a "crosslink callback" for the given
1331  Fossil context. The callback is called at the end of a
1332  successfull fsl_deck_crosslink() operation and provides a way
1333  for the client to perform their own work based on the app having
1334  crosslinked an artifact. Crosslinking happens when artifacts are
1335  saved or upon a rebuild operation.
1336 
1337  Crosslink callbacks are called in an unspecified order and the
1338  library may register its own before the client gets a chance to.
1339 
1340  If _any_ crosslinking callback fails (returns non-0) then the
1341  _whole_ crosslinking fails and is rolled back (which may very
1342  well include pending tags/commits/whatever getting rolled back).
1343 
1344  The state parameter has no meaning for this function, but is
1345  passed on as the final argument to cb(). If not NULL, cbState
1346  "may" be required to outlive f, depending on cbState's exact
1347  client-side internal semantics/use, as there is currently no API
1348  to remove registered crosslink listeners.
1349 
1350  The name parameter is for future use to allow clients to replace
1351  built-in implementations and remove crosslink listeners using
1352  published symbolic names. The name must be non-NULL/empty. If a
1353  listener is registered with a duplicate name then the first one
1354  is replaced. This function does not copy the name bytes - they
1355  are assumed to be static or otherwise to live at least as long
1356  as f. The name may be arbitrarily long, but must have a
1357  terminating NUL byte. It is recommended that clients choose a
1358  namespace/prefix to apply to the names they register. The
1359  library reserves the prefix "fsl::" for its own use, and will
1360  happily overwrite client-registered entries with the same
1361  names. The name string need not be stable across appication
1362  sessions and maybe be a randomly-generated string.
1363 
1364  TODO: publish the name(s) of overrideable crosslinkers
1365  once we have them in place.
1366 */
1367 FSL_EXPORT int fsl_xlink_listener( fsl_cx * f, char const * name,
1368  fsl_deck_xlink_f cb, void * cbState );
1369 
1370 
1371 /**
1372  For the given blob.rid value, returns the blob.size value of
1373  that record via *rv. Returns 0 or higher on success, -1 if a
1374  phantom record is found, -2 if no entry is found, or a smaller
1375  negative value on error (dig around the sources to decode them -
1376  this is not expected to fail unless your system is undergoing a
1377  catastrophe).
1378 
1379  @see fsl_content_blob()
1380  @see fsl_content_get()
1381 */
1383 
1384 /**
1385  For the given blob.rid value, fetches the content field of that
1386  record and overwrites tgt's contents with it (reusing tgt's
1387  memory if it has any and if it can). The blob's contents are
1388  uncompressed if they were stored in compressed form. This
1389  extracts a raw blob and does not apply any deltas - use
1390  fsl_content_get() to fully expand a delta-stored blob.
1391 
1392  Returns 0 on success. On error tgt might be partially updated,
1393  e.g. it might be populated with compressed data instead of
1394  uncompressed. On error tgt's contents should be recycled
1395  (e.g. fsl_buffer_reset()) or discarded (e.g. fsl_buffer_clear())
1396  by the client.
1397 
1398  @see fsl_content_get()
1399  @see fsl_content_size()
1400 */
1401 FSL_EXPORT int fsl_content_blob( fsl_cx * f, fsl_id_t blobRid, fsl_buffer * tgt );
1402 
1403 /**
1404  Functionally similar to fsl_content_blob() but does a lot of
1405  work to ensure that the returned blob is expanded from its
1406  deltas, if any. The tgt buffer's memory, if any, will be
1407  replaced/reused if it has any.
1408 
1409  Returns 0 on success. There are no less than 50 potental
1410  different errors, so we won't bother to list them all. On error
1411  tgt might be partially populated. The basic error cases are:
1412 
1413  - FSL_RC_MISUSE if !tgt or !f.
1414 
1415  - FSL_RC_RANGE if rid<=0 or if an infinite loop is discovered in
1416  the repo delta table links (that is a consistency check to avoid
1417  an infinite loop - that condition "cannot happen" because the
1418  verify-before-commit logic catches that error case).
1419 
1420  - FSL_RC_NOT_A_REPO if f has no repo db opened.
1421 
1422  - FSL_RC_NOT_FOUND if the given rid is not in the repo db.
1423 
1424  - FSL_RC_OOM if an allocation fails.
1425 
1426 
1427  @see fsl_content_blob()
1428  @see fsl_content_size()
1429 */
1430 FSL_EXPORT int fsl_content_get( fsl_cx * f, fsl_id_t blobRid, fsl_buffer * tgt );
1431 
1432 /**
1433  Uses fsl_sym_to_rid() to convert sym to a record ID, then
1434  passes that to fsl_content_get(). Returns 0 on success.
1435 */
1436 FSL_EXPORT int fsl_content_get_sym( fsl_cx * f, char const * sym, fsl_buffer * tgt );
1437 
1438 /**
1439  Returns true if the given rid is marked as PRIVATE in f's current
1440  repository. Returns false (0) on error or if the content is not
1441  marked as private.
1442 */
1444 
1445 /**
1446  Marks the given rid public, if it was previously marked as
1447  private. Returns 0 on success, non-0 on error.
1448 
1449  Note that it is not possible to make public content private.
1450 */
1452 
1453 /**
1454  Generic callback interface for visiting decks. The interface
1455  does not generically require that d survive after this call
1456  returns.
1457 
1458  Implementations must return 0 on success, non-0 on error. Some
1459  APIs using this interface may specify that FSL_RC_BREAK can be
1460  used to stop iteration over a loop without signaling an error.
1461  In such cases the APIs will translate FSL_RC_BREAK to 0 for
1462  result purposes, but will stop looping over whatever it is they
1463  are looping over.
1464 */
1465 typedef int (*fsl_deck_visitor_f)( fsl_cx * f, fsl_deck const * d,
1466  void * state );
1467 
1468 /**
1469  For each unique wiki page name in f's repostory, this calls
1470  cb(), passing it the manifest of the most recent version of that
1471  page. The callback should return 0 on success, FSL_RC_BREAK to
1472  stop looping without an error, or any other non-0 code
1473  (preferably a value from fsl_rc_t) on error.
1474 
1475  The 3rd parameter has no meaning for this function but it is
1476  passed on as-is to the callback.
1477 
1478  ACHTUNG: the deck passed to the callback is transient and will
1479  be cleaned up after the callback has returned, so the callback
1480  must not hold a pointer to it or its contents.
1481 
1482  @see fsl_wiki_load_latest()
1483  @see fsl_wiki_latest_rid()
1484  @see fsl_wiki_names_get()
1485  @see fsl_wiki_page_exists()
1486 */
1487 FSL_EXPORT int fsl_wiki_foreach_page( fsl_cx * f, fsl_deck_visitor_f cb, void * state );
1488 
1489 /**
1490  Fetches the most recent RID for the given wiki page name and
1491  assigns *newId (if it is not NULL) to that value. Returns 0 on
1492  success, FSL_RC_MISUSE if !f or !pageName, FSL_RC_RANGE if
1493  !*pageName, and a host of other potential db-side errors
1494  indicating more serious problems. If no such page is found,
1495  newRid is not modified and this function returns 0 (as opposed
1496  to FSL_RC_NOT_FOUND) because that simplifies usage (so far).
1497 
1498  On error *newRid is not modified.
1499 
1500  @see fsl_wiki_load_latest()
1501  @see fsl_wiki_foreach_page()
1502  @see fsl_wiki_names_get()
1503  @see fsl_wiki_page_exists()
1504 */
1505 FSL_EXPORT int fsl_wiki_latest_rid( fsl_cx * f, char const * pageName, fsl_id_t * newRid );
1506 
1507 /**
1508  Loads the artifact for the most recent version of the given wiki page,
1509  populating d with its contents.
1510 
1511  Returns 0 on success. On error d might be partially populated,
1512  so it needs to be passed to fsl_deck_finalize() regardless of
1513  whether this function succeeds or fails.
1514 
1515  Returns FSL_RC_NOT_FOUND if no page with that name is found.
1516 
1517  @see fsl_wiki_latest_rid()
1518  @see fsl_wiki_names_get()
1519  @see fsl_wiki_page_exists()
1520 */
1521 FSL_EXPORT int fsl_wiki_load_latest( fsl_cx * f, char const * pageName, fsl_deck * d );
1522 
1523 /**
1524  Returns true (non-0) if f's repo database contains a page with the
1525  given name, else false.
1526 
1527  @see fsl_wiki_load_latest()
1528  @see fsl_wiki_latest_rid()
1529  @see fsl_wiki_names_get()
1530  @see fsl_wiki_names_get()
1531 */
1532 FSL_EXPORT char fsl_wiki_page_exists(fsl_cx * f, char const * pageName);
1533 
1534 /**
1535  A helper type for use with fsl_wiki_save(), intended primarily
1536  to help client-side code readability somewhat.
1537 */
1539 /**
1540  Indicates that fsl_wiki_save() must only allow the creation of
1541  a new page, and must fail if such an entry already exists.
1542 */
1544 /**
1545  Indicates that fsl_wiki_save() must only allow the update of an
1546  existing page, and will not create a branch new page.
1547 */
1549 /**
1550  Indicates that fsl_wiki_save() must allow both the update and
1551  creation of pages. Trivia: "upsert" is a common SQL slang
1552  abbreviation for "update or insert."
1553 */
1555 };
1556 
1558 
1559 /**
1560  Saves wiki content to f's repository db.
1561 
1562  pageName is the name of the page to update or create.
1563 
1564  b contains the content for the page.
1565 
1566  userName specifies the user name to apply to the change. If NULL
1567  or empty then fsl_cx_user_get() or fsl_guess_user_name() are
1568  used (in that order) to determine the name.
1569 
1570  mimeType specifies the mime type for the content (may be NULL).
1571  Mime type names supported directly by fossil(1) include (as of
1572  this writing): text/x-fossil-wiki, text/x-markdown,
1573  text/plain
1574 
1575  Whether or not this function is allowed to create a new page is
1576  determined by creationPolicy. If it is
1577  FSL_WIKI_SAVE_MODE_UPDATE, this function will fail with
1578  FSL_RC_NOT_FOUND if no page with the given name already exists.
1579  If it is FSL_WIKI_SAVE_MODE_CREATE and a previous version _does_
1580  exist, it fails with FSL_RC_ALREADY_EXISTS. If it is
1581  FSL_WIKI_SAVE_MODE_UPSERT then both the save-exiting and
1582  create-new cases are allowed. In summary:
1583 
1584  - use FSL_WIKI_SAVE_MODE_UPDATE to allow updates to existing pages
1585  but disallow creation of new pages,
1586 
1587  - use FSL_WIKI_SAVE_MODE_CREATE to allow creating of new pages
1588  but not of updating an existing page.
1589 
1590  - FSL_WIKI_SAVE_MODE_UPSERT allows both updating and creating
1591  a new page on demand.
1592 
1593  Returns 0 on success, or any number fsl_rc_t codes on error. On
1594  error no content changes are saved, and any transaction is
1595  rolled back or a rollback is scheduled if this function is
1596  called while a transaction is active.
1597 
1598 
1599  Potential TODO: add an optional (fsl_id_t*) output parameter
1600  which gets set to the new record's RID.
1601 
1602  @see fsl_wiki_page_exists()
1603  @see fsl_wiki_names_get()
1604 */
1605 FSL_EXPORT int fsl_wiki_save(fsl_cx * f, char const * pageName,
1606  fsl_buffer const * b, char const * userName,
1607  char const * mimeType, fsl_wiki_save_mode_t creationPolicy );
1608 
1609 /**
1610  Fetches the list of all wiki page names in f's current repo db
1611  and appends them as new (char *) strings to tgt. On error tgt
1612  might be partially populated (but this will only happen on an
1613  OOM or serious system-level error).
1614 
1615  It is up to the caller free the entries added to the list. Some
1616  of the possibilities include:
1617 
1618  @code
1619  fsl_list_visit( list, 0, fsl_list_v_fsl_free, NULL );
1620  fsl_list_reserve(list,0);
1621  // Or:
1622  fsl_list_clear(list, fsl_list_v_fsl_free, NULL);
1623  // Or simply:
1624  fsl_list_visit_free( list, 1 );
1625  @endcode
1626 
1627 */
1628 FSL_EXPORT int fsl_wiki_names_get( fsl_cx * f, fsl_list * tgt );
1629 
1630 /**
1631  Represents one file entry in a Manifest/Control Artifact (i.e.,
1632  a checkin version).
1633 
1634  All of the non-const pointers in this class are owned by the
1635  respective instance of the class, and must neither be modified
1636  nor freed except via the appropriate APIs.
1637 */
1638 struct fsl_card_F {
1639  /**
1640  Name of the file.
1641  */
1642  char * name;
1643  /**
1644  UUID of the underlying blob record for the file. NULL for
1645  removed entries.
1646  */
1648  /**
1649  Previous name if the file was renamed, else NULL.
1650  */
1651  char * priorName;
1652  /**
1653  File permissions. Fossil only supports one "permission" per
1654  file, and it does not necessarily map to a real
1655  filesystem-level permissino.
1656 
1657  @see fsl_file_perm_t
1658  */
1660 
1661  /**
1662  An internal optimization. Do not mess with this. When this is
1663  true, the various string members of this struct are not owned
1664  by this struct, but by the deck which created this struct. This
1665  is used when loading decks from storage - the strings are
1666  pointed to the original content data, rather than strdup()'d
1667  copies of it. fsl_card_F_free() will DTRT and delete the
1668  strings (or not).
1669  */
1671 };
1672 
1673 /**
1674  Empty-initialized fsl_card_F structure, intended for use in
1675  initialization when embedding fsl_card_F in another struct or
1676  copy-initializing a const struct.
1677 */
1678 #define fsl_card_F_empty_m { \
1679  NULL/*name*/, \
1680  NULL/*uuid*/, \
1681  NULL/*priorName*/, \
1682  0/*perm*/, \
1683  0/*externalStrings*/ \
1684  }
1685 
1686 /**
1687  Empty-initialized fsl_card_F instance, intended for use in
1688  copy-constructing.
1689 */
1691 
1692 
1693 /**
1694  Represents a J card in a Ticket Control Artifact.
1695 */
1696 struct fsl_card_J {
1697  /**
1698  If true, the new value should be appended to any existing one
1699  with the same key, else it will replace any old one.
1700  */
1701  char append;
1702  /**
1703  For internal use only.
1704  */
1705  unsigned char flags;
1706  /**
1707  The ticket field to update. The bytes are owned by this object.
1708  */
1709  char * field;
1710  /**
1711  The value for the field. The bytes are owned by this object.
1712  */
1713  char * value;
1714 };
1715 /** Empty-initialized fsl_card_J struct. */
1716 #define fsl_card_J_empty_m {0,0,NULL, NULL}
1717 /** Empty-initialized fsl_card_J struct. */
1719 
1720 /**
1721  Represents a tag in a Manifest or Control Artifact.
1722 */
1723 struct fsl_card_T {
1724  /**
1725  The type of tag.
1726  */
1727  fsl_tag_type type;
1728  /**
1729  UUID of the artifact this tag is tagging. When applying a tag to
1730  a new checkin, this value is left empty (=NULL) and gets replaced
1731  by a '*' in the resulting control artifact.
1732  */
1734  /**
1735  The tag's name. The bytes are owned by this object.
1736  */
1737  char * name;
1738  /**
1739  The tag's value. May be NULL/empty. The bytes are owned by
1740  this object.
1741  */
1742  char * value;
1743 };
1744 /** Defaults-initialized fsl_card_T instance. */
1745 #define fsl_card_T_empty_m {FSL_TAGTYPE_INVALID, NULL, NULL,NULL}
1746 /** Defaults-initialized fsl_card_T instance. */
1748 
1749 /**
1750  Represents a Q card in a Manifest or Control Artifact.
1751 */
1752 struct fsl_card_Q {
1753  /** 0==invalid, negative==backed out, positive=cherrypicked. */
1754  int type;
1755  /**
1756  UUID of the target of the cherrypick. The bytes are owned by
1757  this object.
1758  */
1760  /**
1761  UUID of the baseline for the cherrypick. The bytes are owned by
1762  this object.
1763  */
1765 };
1766 /** Empty-initialized fsl_card_Q struct. */
1767 #define fsl_card_Q_empty_m {0, NULL, NULL}
1768 /** Empty-initialized fsl_card_Q struct. */
1770 
1771 /**
1772  Allocates a new J-card record instance
1773 
1774  On success it returns a new record which must eventually be
1775  passed to fsl_card_J_free() to free its resources. On
1776  error (invalid arguments or allocation error) it returns NULL.
1777  field may not be NULL or empty but value may be either.
1778 
1779  These records are immutable - the API provides no way to change
1780  them one they are instantiated.
1781 */
1782 FSL_EXPORT fsl_card_J * fsl_card_J_malloc(char isAppend,
1783  char const * field,
1784  char const * value);
1785 /**
1786  Frees a J-card record created by fsl_card_J_malloc().
1787  Is a no-op if cp is NULL.
1788 */
1790 
1791 
1792 /**
1793  Allocates a new fsl_card_F instance for use with
1794  fsl_deck_F_add2(). Returns NULL for any of these error cases:
1795 
1796  - name is NULL
1797  - uuid is not NULL and fsl_is_uuid(uuid) returns false.
1798  - allocation error
1799 
1800  On success it returns a new object which must eventually be
1801  passed to fsl_card_F_free() to free it.
1802 
1803  @see fsl_card_F_free()
1804 */
1805 FSL_EXPORT fsl_card_F * fsl_card_F_malloc(char const * name,
1806  fsl_uuid_cstr uuid,
1807  fsl_file_perm_t perm,
1808  char const * oldName);
1809 
1810 /**
1811  Frees up any memory owned by t and clears out t's state,
1812  but does not free t.
1813 
1814  @see fsl_card_F_free()
1815 */
1817 
1818 /**
1819  Calls fsl_card_F_clean(t) and then passes t to
1820  fsl_free().
1821 
1822  @see fsl_card_F_clean()
1823 */
1825 
1826 /**
1827  Allocates a new fsl_card_T instance. If any of the pointer
1828  parameters are non-NULL, their values are assumed to be
1829  NUL-terminated strings, which this function copies. Returns
1830  NULL on allocation error. The returned value must eventually be
1831  passed to fsl_card_T_finalize() to free its resources.
1832 
1833  If uuid is not NULL and fsl_is_uuid(uuid) returns false then
1834  this function returns NULL. If it is NULL and gets assigned
1835  later, it must conform to fsl_is_uuid()'s rules or downstream
1836  results are undefined.
1837 
1838  @see fsl_card_T_free()
1839 */
1840 FSL_EXPORT fsl_card_T * fsl_card_T_malloc(fsl_tag_type tagType,
1841  fsl_uuid_cstr uuid,
1842  char const * name,
1843  char const * value);
1844 /**
1845  Calls fsl_card_T_clean(t) and then passes t to
1846  fsl_free().
1847 
1848  @see fsl_card_T_clean()
1849 */
1851 
1852 /**
1853  Frees up any memory owned by t and clears out t's state,
1854  but does not free t.
1855 
1856  @see fsl_card_T_free()
1857 */
1859 
1860 
1861 /**
1862  Allocates a new cherrypick record instance. The type argument
1863  must be negative for a backed-out change, positive for a
1864  cherrypicked change. target must be a valid UUID string. If
1865  baseline is not NULL then it also must be a valid UUID.
1866 
1867  On success it returns a new record which must eventually be
1868  passed to fsl_card_Q_free() to free its resources. On
1869  error (invalid arguments or allocation error) it returns NULL.
1870 
1871  These records are immutable - the API provides no way to change
1872  them once they are instantiated.
1873 */
1875  fsl_uuid_cstr target,
1876  fsl_uuid_cstr baseline);
1877 /**
1878  Frees a cherrypick record created by fsl_card_Q_malloc().
1879  Is a no-op if cp is NULL.
1880 */
1882 
1883 /**
1884  Returns true (non-0) if f is not NULL and f has an opened repo
1885  which contains a checkin with the given rid, else it returns
1886  false.
1887 
1888  As a special case, if rid==0 then this only returns true
1889  if the repository currently has no content in the blob
1890  table.
1891 */
1893 
1894 
1895 /**
1896  Fetches the list of all directory names for a given record id or
1897  (if rid is negative) the whole repo over all of its combined
1898  history. Each name entry in the list is appended to tgt. The
1899  results are reduced to unique names only and are sorted
1900  lexically. If addSlash is true then each entry will include a
1901  trailing slash character, else it will not. The list does not
1902  include an entry for the top-most directory.
1903 
1904  If rid is less than 0 then the directory list across _all_
1905  versions is returned. If it is 0 then the current checkout's RID
1906  is used (if a checkout is opened, otherwise a usage error is
1907  triggered). If it is positive then only directories for the
1908  given checkin RID are returned. If rid is specified, it is
1909  assumed to be the record ID of a commit (manifest) record, and
1910  it is impossible to distinguish between the results "invalid
1911  rid" and "empty directory list" (which is a legal result).
1912 
1913  On success it returns 0 and tgt will have a number of (char *)
1914  entries appended to it equal to the number of subdirectories in
1915  the repo (possibly 0).
1916 
1917  Returns non-0 on error, FSL_RC_MISUSE if !f, !tgt. On other
1918  errors error tgt might have been partially populated and the
1919  list contents should not be considered valid/complete.
1920 
1921  Ownership of the returned strings is transfered to the caller,
1922  who must eventually free each one using
1923  fsl_free(). fsl_list_visit_free() is the simplest way to free
1924  them all at once.
1925 */
1926 FSL_EXPORT int fsl_repo_dir_names( fsl_cx * f, fsl_id_t rid, fsl_list * tgt, char addSlash );
1927 
1928 
1929 /**
1930  ZIPs up a copy of the contents of a specific version from f's
1931  opened repository db. sym is the symbolic name for the checkin
1932  to ZIP. filename is the name of the ZIP file to output the
1933  result to. See fsl_zip_writer for details and caveats of this
1934  library's ZIP creation. If vRootDir is not NULL and not empty
1935  then each file injected into the ZIP gets that directory
1936  prepended to its name.
1937 
1938  If progressVisitor is not NULL then it is called once just
1939  before each file is processed, passed the F-card for the file
1940  about to be zipped and the progressState parameter. If it
1941  returns non-0, ZIPping is cancelled and that error code is
1942  returned. This is intended primarily for providing feedback on
1943  the update process, but could also be used to cancel the
1944  operation between files.
1945 
1946  BUG: this function does not honor symlink content in a
1947  fossil-compatible fashion. If it encounters a symlink entry
1948  during ZIP generation, it will fail and f's error state will be
1949  updated with an explanation of this shortcoming.
1950 
1951  @see fsl_zip_writer
1952  @see fsl_card_F_visitor_f()
1953 */
1954 FSL_EXPORT int fsl_repo_zip_sym_to_filename( fsl_cx * f, char const * sym,
1955  char const * vRootDir,
1956  char const * fileName,
1957  fsl_card_F_visitor_f progressVisitor,
1958  void * progressState);
1959 
1960 
1961 /**
1962  Callback state for use with fsl_repo_extract_f() implementations
1963  to stream a given version of a repository's file's, one file at a
1964  time, to a client. Instances are never created by client code,
1965  only by fsl_repo_extract() and its delegates, which pass them to
1966  client-provided fsl_repo_extract_f() functions.
1967 */
1969  /**
1970  Client state passed to fsl_repo_extract(). Its interpretation
1971  is callback-implementation-dependent.
1972  */
1973  void * state;
1974  /**
1975  The F-card being iterated over. This holds the repo-level
1976  metadata associated with the file.
1977 
1978  Deleted files are NOT reported via the extraction process
1979  because reporting them accurately is trickier and more
1980  expensive than it could be. Thus this member's uuid field
1981  will always be non-NULL.
1982  */
1983  fsl_card_F const * fc;
1984 
1985  /**
1986  Holds the full, undelta'd/uncompressed content of fc's file
1987  record. The content bytes are owned by fsl_repo_extract() and
1988  are invalidated as soon as this callback returns, so the
1989  callback must copy/consume them immediately if needed.
1990  */
1992  /**
1993  The associated Fossil context.
1994  */
1996  /**
1997  RID of the checkin version for this file. For a given call to
1998  fsl_repo_extract(), this number will be the same across all
1999  calls to the callback function.
2000  */
2002  /**
2003  File-level blob.rid for fc. Can be used with, e.g.,
2004  fsl_mtime_of_manifest_file().
2005 
2006  It is 0 for files deleted somewhere between the parent and
2007  checkin version.
2008  */
2010 
2011 };
2013 
2014 /**
2015  A callback type for use with fsl_repo_extract(). See
2016  fsl_repo_extract_state for the meanings of xstate's various
2017  members. The xstate memory must be considered invalidated
2018  immediately after this function returns, thus implementations
2019  must copy or consume anything they need from xstate before
2020  returning.
2021 
2022  Implementations must return 0 on success. As a special case, if
2023  FSL_RC_BREAK is returned then fsl_repo_extract() will stop
2024  looping over files but will report it as success (by returning
2025  0). Any other code causes extraction looping to stop and is
2026  returned as-is to the caller of fsl_repo_extract().
2027 
2028  When returning an error, the client may use fsl_cx_err_set() to
2029  populate state->f with a useful error message which will
2030  propagate back up through the call stack.
2031 
2032  @see fsl_repo_extract()
2033 */
2034 typedef int (*fsl_repo_extract_f)( fsl_repo_extract_state const * xstate );
2035 
2036 
2037 /**
2038  Extracts the contents of the given checkin version ID, sending
2039  the appropriate version of each file's contents to the given
2040  callback.
2041 
2042  For each file in the given checkin, callback() is passed a
2043  fsl_repo_extract_state instance containting enough information
2044  to, e.g., unpack the contents to a working directory, add it to a
2045  compressed archive, or send it to some other destination.
2046 
2047  Returns 0 on success, non-0 on error. Will fail if f has no
2048  opened repository db.
2049 
2050  If the callback returns any code other than 0 or FSL_RC_BREAK,
2051  looping over the list of files ends and this function returns
2052  that value. FSL_RC_BREAK causes looping to stop but 0 is
2053  returned.
2054 
2055  Files deleted by the given version are not reported to the callback
2056  (because getting sane semantics has proven to be tricker and more
2057  costly than it's worth).
2058 
2059  See fsl_repo_extract_f() for more details about the semantics of
2060  the callback.
2061 
2062  Fossil's internal metadata format guarantees that files will passed
2063  be passed to the callback in "lexical order" (as defined by
2064  fossil's manifest format definition). i.e. the files will be passed
2065  in case-sensitive, alphabetical order. Note that upper-case letters
2066  sort before lower-case ones.
2067 */
2069  fsl_repo_extract_f callback, void * callbackState );
2070 
2071 /**
2072  Equivalent to fsl_tag_rid() except that it takes a symbolic
2073  artifact name in place of an artifact ID as the third
2074  argumemnt.
2075 
2076  This function passes symToTag to fsl_sym_to_rid(), and on
2077  success passes the rest of the parameters as-is to
2078  fsl_tag_rid(). See that function the semantics of the other
2079  arguments and the return value, as well as a description of the
2080  side effects.
2081 */
2082 FSL_EXPORT int fsl_tag_sym( fsl_cx * f, fsl_tag_type tagType,
2083  char const * symToTag, char const * tagName,
2084  char const * tagValue, char const * userName,
2085  fsl_double_t mtime, fsl_id_t * newId );
2086 
2087 /**
2088  Adds a control record to f's repositoriy that either creates or
2089  cancels a tag.
2090 
2091  artifactRidToTag is the RID of the record to be tagged.
2092 
2093  tagType is the type (add, cancel, or propagate) of tag.
2094 
2095  tagName is the name of the tag. Must not be NULL/empty.
2096 
2097  tagValue is the optional value for the tag. May be NULL.
2098 
2099  userName is the user's name to apply to the artifact. May not be
2100  empty/NULL. Use fsl_guess_user_name() to try to figure out a
2101  proper user name based on the environment. See also:
2102  fsl_cx_user_get(), but note that the application must first
2103  use fsl_cx_user_set() to set a context's user name.
2104 
2105  mtime is the timestamp for the new artifact. Pass a value <=0 to
2106  use the current time.
2107 
2108  If newId is not NULL then on success the rid of the new tag control
2109  artifact is assigned to *newId.
2110 
2111  Returns 0 on success and has about a million and thirteen
2112  possible error conditions. On success a new artifact record is
2113  written to the db, its RID being written into newId as described
2114  above.
2115 
2116  If the artifact being tagged is private, the new tag is also
2117  marked as private.
2118 
2119 */
2120 FSL_EXPORT int fsl_tag_rid( fsl_cx * f, fsl_tag_type tagType,
2121  fsl_id_t artifactRidToTag, char const * tagName,
2122  char const * tagValue, char const * userName,
2123  fsl_double_t mtime, fsl_id_t * newId );
2124 
2125 /**
2126  Returns non-0 (true) if the checkin with the given rid is a
2127  leaf, 0 (false) if not. Returns 0 if !f, f has no repo db
2128  opened, the query fails (likely indicating that it is not a
2129  repository db), or just about any other conceivable non-success
2130  case.
2131 
2132  A leaf is a commit which has no children in the same branch.
2133 */
2134 FSL_EXPORT char fsl_rid_is_leaf(fsl_cx * f, fsl_id_t rid);
2135 
2136 /**
2137  Counts the number of primary non-branch children for the given
2138  check-in.
2139 
2140  A primary child is one where the parent is the primary parent, not
2141  a merge parent. A "leaf" is a node that has zero children of any
2142  kind. This routine counts only primary children.
2143 
2144  A non-branch child is one which is on the same branch as the parent.
2145 
2146  Returns a negative value on error.
2147 */
2149 
2150 /**
2151  Looks for the delta table record where rid==deltaRid, and
2152  returns that record's srcid via *rv. Returns 0 on success, non-0
2153  on error. If no record is found, *rv is set to 0 and 0 is
2154  returned (as opposed to FSL_RC_NOT_FOUND) because that generally
2155  simplifies the error checking.
2156 */
2157 FSL_EXPORT int fsl_delta_src_id( fsl_cx * f, fsl_id_t deltaRid, fsl_id_t * rv );
2158 
2159 
2160 /**
2161  Return true if the given artifact ID should is listed in f's
2162  shun table, else false.
2163 */
2165 
2166 /**
2167  Given a fsl_cx with an opened checkout, and a filename, this
2168  function canonicalizes zOrigName to a form suitable for use as
2169  an in-repo filename, _appending_ the results to pOut. If pOut is
2170  NULL, it performs its normal checking but does not write a
2171  result, other than to return 0 for success.
2172 
2173  As a special case, if zOrigName refers to the top-level checkout
2174  directory, it resolves to either "." or "./", depending on whether
2175  zOrigName contains a trailing slash.
2176 
2177  If relativeToCwd is true then the filename is canonicalized
2178  based on the current working directory (see fsl_getcwd()),
2179  otherwise f's current checkout directory is used as the virtual
2180  root.
2181 
2182  If the input name contains a trailing slash, it is retained in
2183  the output sent to pOut except in the top-dir case mentioned
2184  above.
2185 
2186  Returns 0 on success, meaning that the value appended to pOut
2187  (if not NULL) is a syntactically valid checkout-relative path.
2188 
2189  Returns FSL_RC_RANGE if zOrigName points to a path outside
2190  of f's current checkout root.
2191 
2192  Returns FSL_RC_NOT_A_CHECKOUT if f has no checkout opened.
2193 
2194  Returns FSL_RC_MISUSE if !f, !zOrigName, FSL_RC_OOM on an
2195  allocation error.
2196 
2197  This function does not validate whether or not the file actually
2198  exists, only that its name is potentially valid as a filename
2199  for use in a checkout (though other, downstream rules might prohibit that, e.g.
2200  the filename "..../...." is not valid but is not seen as invalid by
2201  this function). (Reminder to self: we could run the end result through
2202  fsl_is_simple_pathname() to catch that?)
2203 */
2204 FSL_EXPORT int fsl_checkout_filename_check( fsl_cx * f, char relativeToCwd,
2205  char const * zOrigName, fsl_buffer * pOut );
2206 
2207 /**
2208  Compute the "mtime" of the file given whose blob.rid is "fid"
2209  that is part of check-in "vid". The mtime will be the mtime on
2210  vid or some ancestor of vid where fid first appears. Note that
2211  fossil does not track the "real" mtimes of files, it only
2212  computes reasonable estimates for those files based on the
2213  timestamps of their most recent checkin in the ancestry of vid.
2214 
2215  On success, if pMTime is not null then the result is written to
2216  *pMTime.
2217 
2218  If fid is 0 or less then the checkin time of vid is written to
2219  pMTime (this is a much less expensive operation, by the way).
2220  In this particular case, FSL_RC_NOT_FOUND is returned if vid is
2221  not a valid checkin version.
2222 
2223  Returns 0 on success, non-0 on error. Returns FSL_RC_NOT_FOUND
2224  if fid is not found in vid.
2225 
2226  This routine is much more efficient if used to answer several
2227  queries in a row for the same manifest (the vid parameter). It
2228  is least efficient when it is passed intermixed manifest IDs,
2229  e.g. (1, 3, 1, 4, 1,...). This is a side-effect of the caching
2230  used in the computation of ancestors for a given vid.
2231 */
2233 
2234 /**
2235  A convenience form of fsl_mtime_of_manifest_file() which looks up
2236  fc's RID based on its UUID. vid must be the RID of the checkin
2237  version fc originates from. See fsl_mtime_of_manifest_file() for
2238  full details - this function simply calculates the 3rd argument
2239  for that one.
2240 */
2241 FSL_EXPORT int fsl_mtime_of_F_card(fsl_cx * f, fsl_id_t vid, fsl_card_F const * fc, fsl_time_t *pMTime);
2242 
2243 /**
2244  Adds the given filename to the current checkout vfile list of
2245  files as a to-be-added file, or updates an existing record if
2246  one exists.
2247 
2248  If relativeToCwd is true (non-0) then the filename is
2249  resolved/canonicalized based on the current working directory
2250  (see fsl_getcwd()), otherwise f's current checkout directory is
2251  used as the virtual root. This makes a subtle yet important
2252  difference in how the name is resolved. CLI apps which take file
2253  names from the user will generally want to set relativeToCwd to
2254  true. GUI apps, OTOH, will possibly need it to be false,
2255  depending on how they resolve and pass on the filenames.
2256 
2257  This function ensures that zFilename gets canonicalized and can
2258  be found under the checkout directory, and fails if no such file
2259  exists (checking against the canonicalized name).
2260 
2261  Returns 0 on success, non-0 on error.
2262 
2263  Note that unlike fsl_checkout_file_rm(), this routine cannot
2264  recursively add files from a directory name. Fixing that is on
2265  the TODO list.
2266 
2267  @see fsl_checkout_file_rm()
2268 */
2269 FSL_EXPORT int fsl_checkout_file_add( fsl_cx * f, char relativeToCwd, char const * zFilename );
2270 
2271 /**
2272  The converse of fsl_checkout_file_add(), this queues a file for
2273  removal from the current checkout. The arguments have identical
2274  meanings as for fsl_checkout_file_add() except that this routine
2275  does not ensure that the resolved filename actually exists - it
2276  only normalizes zFilename into its repository-friendly form.
2277 
2278  If recurseDirs is true then if zFilename refers to a directory
2279  then this operation queues all files under that directory
2280  (recursively) for removal. In this case, it is irrelevant
2281  whether or not zFilename ends in a trailing slash or not.
2282 
2283  Returns 0 on success, any of a number of non-0 codes on error.
2284  Returns FSL_RC_MISUSE if !f, !zFilename, or !*zFilename.
2285  Returns FSL_RC_NOT_A_CHECKOUT if f has no opened checkout.
2286 
2287  @see fsl_checkout_file_add()
2288 */
2289 FSL_EXPORT int fsl_checkout_file_rm( fsl_cx * f, char relativeToCwd, char const * zFilename,
2290  char recurseDirs );
2291 
2292 /**
2293  Change-type flags for use with fsl_checkout_changes_visit() and
2294  friends.
2295 */
2297 /**
2298  Sentinel placeholder value.
2299 */
2301 /**
2302  Indicates that a file was modified in some unspecified way.
2303 */
2305 /**
2306  Indicates that a file was modified as the result of a merge.
2307 */
2309 /**
2310  Indicates that a file was added as the result of a merge.
2311 */
2313 /**
2314  Indicates that a file was modified as the result of an
2315  integrate-merge.
2316 */
2318 /**
2319  Indicates that a file was added as the result of an
2320  integrate-merge.
2321 */
2323 /**
2324  Indicates that a file was added.
2325 */
2327 /**
2328  Indicates that a file was removed.
2329 */
2331 /**
2332  Indicates that a file is missing from the local checkout.
2333 */
2335 /**
2336  Indicates that a file was renamed.
2337 */
2339 /**
2340  NOT YET USED.
2341 
2342  Indicates that a file contains conflict markers.
2343 */
2345 /**
2346  NOT YET USED.
2347 
2348  Indicates that a file in the changes table references
2349  a non-file on disk.
2350 */
2352 /**
2353  NOT YET USED.
2354 
2355  Indicates that a file is part of a cherrypick merge.
2356 */
2358 /**
2359  NOT YET USED.
2360 
2361  Indicates that a file is part of a backout.
2362 */
2364 };
2365 
2367 
2368 /**
2369  Sets up the vfile table in f's opened checkout db and scans the
2370  checkout root directory's contents for changes compared to the
2371  pristine checkout state. It records any changes in the vfile
2372  table.
2373 
2374  Returns 0 on success, non-0 on error, FSL_RC_MISUSE
2375  if !f.
2376 
2377  For compatibility with fossil(1), this routine clears the vfile
2378  table of any entries not related to the current checkout.
2379 
2380  TODO: a variant of this which scans only a given file or directory.
2381 
2382  @see fsl_checkout_changes_visit()
2383 */
2385 
2386 /**
2387  A typedef for visitors of checkout status information via
2388  fsl_checkout_changes_visit(). Implementions will receive the
2389  last argument passed to fsl_checkout_changes_visit() as their
2390  first argument. The second argument indicates the type of change
2391  and the third holds the repository-relative name of the file.
2392 
2393  If changes is FSL_CKOUT_CHANGE_RENAMED then origName will hold
2394  the original name, else it will be NULL.
2395 
2396  Implementations must return 0 on success, non-zero on error. On
2397  error any looping performed by fsl_checkout_changes_visit() will
2398  stop and this function's result code will be returned.
2399 
2400  @see fsl_checkout_changes_visit()
2401 */
2402 typedef int (*fsl_checkout_changes_f)(void * state, fsl_checkout_change_t change,
2403  char const * filename,
2404  char const * origName);
2405 
2406 /**
2407  Compares the changes of f's local checkout against repository
2408  version vid (checkout version if vid is negative). For each
2409  change detected it calls visitor(state,...) to report the
2410  change. If visitor() returns non-0, that code is returned from
2411  this function. If doChangeScan is true then
2412  fsl_checkout_changes_scan() is called by this function before
2413  iterating, otherwise it is assumed that the caller has called
2414  that or has otherwise ensured that the checkout db's vfile table
2415  has been populated.
2416 
2417  Returns 0 on success.
2418 
2419  @see fsl_checkout_changes_scan()
2420 */
2422  char doChangeScan,
2423  fsl_checkout_changes_f visitor,
2424  void * state );
2425 
2426 /**
2427  Holds options for use with fsl_branch_create().
2428 */
2430  /**
2431  The checkin RID from which the branch should originate.
2432  */
2434  /**
2435  The name of the branch. May not be NULL or empty.
2436  */
2437  char const * name;
2438  /**
2439  User name for the branch. If NULL, fsl_cx_user_get() will
2440  be used.
2441  */
2442  char const * user;
2443  /**
2444  Optional comment (may be NULL). If NULL or empty, a default
2445  comment is generated (because fossil requires a non-empty
2446  comment string).
2447  */
2448  char const * comment;
2449  /**
2450  Optional background color for the fossil(1) HTML timeline
2451  view. Must be in \#RRGGBB format, but this API does not
2452  validate it as such.
2453  */
2454  char const * bgColor;
2455  /**
2456  The julian time of the branch. If 0 or less, default is the
2457  current time.
2458  */
2460  /**
2461  If true, the branch will be marked as private.
2462  */
2464 };
2466 #define fsl_branch_opt_empty_m { \
2467  0/*basisRid*/, NULL/*name*/, \
2468  NULL/*user*/, NULL/*comment*/, \
2469  NULL/*bgColor*/, \
2470  0.0/*mtime*/, 0/*isPrivate*/ \
2471  }
2473 
2474 /**
2475  Creates a new branch in f's repository. The 2nd paramter holds
2476  the options describing the branch. The 3rd parameter may be
2477  NULL, but if it is not then on success the RID of the new
2478  manifest is assigned to *newRid.
2479 
2480  In Fossil branches are implemented as tags. The branch name
2481  provided by the client will cause the creation of a tag with
2482  name name plus a "sym-" prefix to be created (if needed).
2483  "sym-" denotes that it is a "symbolic tag" (fossil's term for
2484  "symbolic name applying to one or more checkins,"
2485  i.e. branches).
2486 
2487  Creating a branch cancels all other branch tags which the new
2488  branch would normally inherit.
2489 
2490  Returns 0 on success, non-0 on error.
2491 */
2492 FSL_EXPORT int fsl_branch_create(fsl_cx * f, fsl_branch_opt const * opt, fsl_id_t * newRid );
2493 
2494 
2495 /**
2496  Don't use this yet - the whole checkin-queue mechanism is an
2497  experiment at this point.
2498 
2499  Adds the given file f's list of "selected" files - the list of
2500  filenames which should be included in the next commit
2501  (see fsl_checkin_commit()).
2502 
2503  Warning: if this function is not called before
2504  fsl_checkin_commit(), then fsl_checkin_commit() will select all
2505  modified, added, removed, or renamed files by default.
2506 
2507  zName must be a non-empty NUL-terminated string and its bytes are
2508  copied. The filename is canonicalized via
2509  fsl_checkout_filename_check() - see that function for the meaning
2510  of the relativeToCwd parameter.
2511 
2512  The resolved name must refer to either a single vfile.pathname
2513  value in the current vfile table (i.e. in the current checkout,
2514  though possibly newly-added and not necessarily committed), or it
2515  must refer to a directory, under which all modified, added,
2516  deleted, or renamed files are queued up for the next commit.
2517 
2518  If given a single file name it returns FSL_RC_NOT_FOUND if the
2519  file is not in the current checkout. In this case f's error state
2520  is updated with a description of the problem.
2521 
2522  If given a directory name, it does not validate that any changes
2523  are actually detected for queuing up (that detection comes at the
2524  final commit stage).
2525 
2526  The change-state of the file(s) is not actually checked by this
2527  function, other than to confirm that the file is indeed listed in
2528  the current checkout. That means that the file may still be
2529  modified by the client before the commit takes place, and the
2530  changes on disk at the point of the fsl_checkin_commit() are the
2531  ones which get saved (or not).
2532 
2533  Returns 0 on success, FSL_RC_MISUSE if either pointer is NULL,
2534  or *zName is NUL. Returns FSL_RC_OOM on allocation error.
2535 
2536  On error f's error state might (depending on the nature of the
2537  problem) contain more details.
2538 
2539  Returns 0 and has no side-effects if zName is already in the
2540  checkin queue. This function honors the
2541  fsl_cx_is_case_sensitive() setting when comparing names but the
2542  check for the repo-level file is case-sensitive! That's arguably
2543  a bug.
2544 
2545  @see fsl_checkin_file_is_enqueued()
2546  @see fsl_checkin_file_dequeue()
2547  @see fsl_checkin_discard()
2548  @see fsl_checkin_commit()
2549 */
2550 FSL_EXPORT int fsl_checkin_file_enqueue(fsl_cx * f, char const * zName,
2551  char relativeToCwd);
2552 
2553 /**
2554  The opposite of fsl_checkin_file_enqueue(), then removes the
2555  given file or directory name from f's checkin queue. Returns 0 on
2556  succes. Unlike fsl_checkin_file_enqueue(), this function does
2557  little validation on the input and simply asks the internals to
2558  clean up. Specifically, it does not return an error if this
2559  operation finds no entries to unqueue. If zName is empty or NULL
2560  then ALL files are unqueued from the pending checkin.
2561 
2562  If relativeToCwd is true (non-0) then zName is resolved based on
2563  the current directory, otherwise it is resolved based on the
2564  checkout's root directory.
2565 
2566 
2567  @see fsl_checkin_file_enqueue()
2568  @see fsl_checkin_file_is_enqueued()
2569  @see fsl_checkin_discard()
2570  @see fsl_checkin_commit()
2571 */
2572 FSL_EXPORT int fsl_checkin_file_dequeue(fsl_cx * f, char const * zName,
2573  char relativeToCwd);
2574 
2575 /**
2576  Returns true (non-0) if the file named by zName is in f's current
2577  file checkin queue. If NO files are in the current selection
2578  queue then this routine assumes that ALL files are implicitely
2579  selected. As long as at least once file is enqueud (via
2580  fsl_checkin_file_enqueue()) then this function only returns true
2581  for files which have been explicitly enqueued.
2582 
2583  If relativeToCwd then zName is resolved based on the current
2584  directory, otherwise it is resolved based on the checkout's
2585  root directory.
2586 
2587  This function returning true does not necessarily indicate that
2588  the file _will_ be checked in at the next commit. If the file has
2589  not been modified at commit-time then it will not be part of the
2590  commit.
2591 
2592  This function honors the fsl_cx_is_case_sensitive() setting
2593  when comparing names.
2594 
2595  Achtung: this does not resolve directory names like
2596  fsl_checkin_file_enqueue() and fsl_checkin_file_dequeue() do. It
2597  only works with file names.
2598 
2599  @see fsl_checkin_file_enqueue()
2600  @see fsl_checkin_file_dequeue()
2601  @see fsl_checkin_discard()
2602  @see fsl_checkin_commit()
2603 */
2604 FSL_EXPORT char fsl_checkin_file_is_enqueued(fsl_cx * f, char const * zName,
2605  char relativeToCwd);
2606 
2607 /**
2608  Discards any state accumulated for a pending checking,
2609  including any files queued via fsl_checkin_file_enqueue()
2610  and tags added via fsl_checkin_T_add().
2611 
2612  @see fsl_checkin_file_enqueue()
2613  @see fsl_checkin_file_dequeue()
2614  @see fsl_checkin_file_is_enqueued()
2615  @see fsl_checkin_commit()
2616  @see fsl_checkin_T_add()
2617 */
2619 
2620 /**
2621  Parameters for fsl_checkin_commit().
2622 
2623  Checkins are created in a multi-step process:
2624 
2625  - fsl_checkin_file_enqueue() queues up a file or directory for
2626  commit at the next commit.
2627 
2628  - fsl_checkin_file_dequeue() removes an entry, allowing
2629  UIs to toggle files in and out of a checkin before
2630  committing it.
2631 
2632  - fsl_checkin_file_is_enqueued() can be used to determine whether
2633  a given name is already enqueued or not.
2634 
2635  - fsl_checkin_T_add() can be used to T-cards (tags) to a
2636  deck. Branch tags are intended to be applied via the
2637  fsl_checkin_opt::branch member.
2638 
2639  - fsl_checkin_discard() can be used to cancel any pending file
2640  enqueuings, effectively cancelling a commit (which can be
2641  re-started by enqueuing another file).
2642 
2643  - fsl_checkin_commit() creates a checkin for the list of enqueued
2644  files (defaulting to all modified files in the checkout!). It
2645  takes an object of this type to specify a variety of parameters
2646  for the check.
2647 
2648  Note that this API uses the terms "enqueue" and "unqueue" rather
2649  than "add" and "remove" because those both have very specific
2650  (and much different) meanings in the overall SCM scheme.
2651 */
2653  /**
2654  The commit message. May not be empty - the library
2655  forbids empty checkin messages.
2656  */
2657  char const * message;
2658 
2659  /**
2660  The optional mime type for the message. Only set
2661  this if you know what you're doing.
2662  */
2663  char const * messageMimeType;
2664 
2665  /**
2666  The user name for the checkin. If NULL or empty, it defaults to
2667  fsl_cx_user_get(). If that is NULL, a FSL_RC_RANGE error is
2668  triggered.
2669  */
2670  char const * user;
2671 
2672  /**
2673  Don't use this yet - it is not yet tested all that well.
2674 
2675  If not NULL, makes the checkin the start of a new branch with
2676  this name.
2677  */
2678  char const * branch;
2679 
2680  /**
2681  If this->branch is not NULL, this is applied as its "bgcolor"
2682  propagating property. If this->branch is NULL then this is
2683  applied as a one-time color tag to the checkin.
2684 
2685  It must be NULL, empty, or in a form usable by HTML/CSS,
2686  preferably \#RRGGBB form. Length-0 values are ignored (as if
2687  they were NULL).
2688  */
2689  char const * bgColor;
2690 
2691  /**
2692  If true, the checkin will be marked as private, otherwise it
2693  will be marked as private or public, depending on whether or
2694  not it inherits private content.
2695  */
2697 
2698  /**
2699  Whether or not to calculate an R-card. Doing so is very
2700  expensive (memory and I/O) but it adds another layer of
2701  consistency checking to manifest files. In practice, the R-card
2702  is somewhat superfluous and the cost of calculating it has
2703  proven painful on very large repositories. fossil(1) creates an
2704  R-card for all checkins but does not require that one be set
2705  when it reads a manifest.
2706  */
2708 
2709  /**
2710  Whether to allow (or try to force) a delta manifest or not. 0
2711  means no deltas allowed - it will generate a baseline
2712  manifest. Greater than 0 forces generation of a delta if
2713  possible (if one can be readily found) even if doing so would not
2714  save a notable amount of space. Less than 0 means to
2715  decide via some heuristics.
2716 
2717  A "readily available" baseline means either the current
2718  checkout is a baseline or has a baseline. In either case, we
2719  can use that as a baseline for a delta. i.e. a baseline
2720  "should" basically available except on the initial checkin,
2721  which has neither a parent checkin nor a baseline.
2722 
2723  The current behaviour for "auto-detect" mode is: it will
2724  generate a delta if a baseline is "readily available." Once it calculates a delta form, it calculates
2725  whether that form saves any appreciable space/overhead compared
2726  to whether a baseline manifest was generated. If so, it
2727  discards the delta and re-generates the manifest as a
2728  baseline. The "force" behaviour (deltaPolicy>0) bypasses the
2729  "is it too big?" test, and is only intended for testing, not
2730  real-life use.
2731  */
2733 
2734  /**
2735  Tells the checkin to close merged-in branches (merge type of
2736  0). INTEGRATE merges (type=-4) are always closed by a
2737  checkin. This does not apply to CHERRYPICK (type=-1) and
2738  BACKOUT (type=-2) merges.
2739  */
2741 
2742  /**
2743  Time of the checkin. If 0 or less, the current time
2744  is used.
2745  */
2747 
2748  /**
2749  If this is not NULL then the committed manifest will include a
2750  tag which closes the branch. The value of this string will be
2751  the value of the "closed" tag, and the value may be an empty
2752  string. The intention is that this gets set to a comment about
2753  why the branch is closed, but it is in no way mandatory.
2754  */
2755  char const * closeBranch;
2756 
2757  /**
2758  Tells fsl_checkin_commit() to dump the generated manifest to
2759  this file. Intended only for debugging and testing. Checking in
2760  will fail if this file cannot be opened for writing.
2761  */
2762  char const * dumpManifestFile;
2763  /*
2764  fossil(1) has many more options. We might want to wrap some of
2765  it up in the "incremental" state (f->ckin.mf).
2766 
2767  TODOs:
2768 
2769  A callback mechanism which supports the user cancelling
2770  the checkin. It is (potentially) needed for ops like
2771  confirming the commit of CRNL-only changes.
2772  */
2773 };
2774 
2775 /**
2776  Empty-initialized fsl_checkin_opt instance, intended for use in
2777  const-copy constructing.
2778 */
2779 #define fsl_checkin_opt_empty_m { \
2780  NULL/*message*/, \
2781  NULL/*messageMimeType*/, \
2782  NULL/*user*/, \
2783  NULL/*branch*/, \
2784  NULL/*bgColor*/, \
2785  0/*isPrivate*/, \
2786  1/*calcRCard*/, \
2787  -1/*deltaPolicy*/, \
2788  0/*integrate*/, \
2789  0.0/*julianTime*/, \
2790  NULL/*closeBranch*/, \
2791  NULL/*dumpManifestFile*/ \
2792  }
2793 
2794 /**
2795  Empty-initialized fsl_checkin_opt instance, intended for use in
2796  copy-constructing. It is important that clients copy this value
2797  (or fsl_checkin_opt_empty_m) to cleanly initialize their
2798  fsl_checkin_opt instances, as this may set default values which
2799  (e.g.) a memset() would not.
2800 */
2802 
2803 /**
2804  Do not use - under construction/testing. Very dangerous. Stay
2805  away. If you choose to ignore this warning, then read on...
2806 
2807  This creates a "checkin manifest" for the current checkout.
2808 
2809  Its primary inputs is a list of files to commit. This list
2810  is provided by the client by calling fsl_checkin_file_enqueue()
2811  one or more times. If no files are explicitely selected
2812  (enqueued) then it calculates which local files have changed vs
2813  the current checkout and selects all of those.
2814 
2815  Non-file inputs are provided via the opt parameter.
2816 
2817  Tip: to implement a "dry-run" mode, simply wrap this call in a
2818  transaction started on the fsl_cx_db_checkout() db handle
2819  (passing it to fsl_db_transaction_begin()), then, after this
2820  call, either cal; fsl_db_transaction_rollback() (to implement
2821  dry-run mode) or fsl_db_transaction_commit() (for "wet-run"
2822  mode). If this function returns non-0, such a transaction should
2823  _always_ be rolled back!
2824 
2825  On success, it returns 0 and...
2826 
2827  - If newRid is not NULL, it is assigned the new checkin's RID
2828  value.
2829 
2830  - If newUuid is not NULL, it is assigned the new checkin's UUID
2831  value. Ownership of the bytes is passed to the caller, who must
2832  eventually pass them to fsl_free() to free them.
2833 
2834  On error non-0 is returned and f's error state may (depending on
2835  the nature of the problem) contain details about the problem.
2836  Note, however, that any error codes returned here may have
2837  arrived from several layers down in the internals, and may not
2838  have a single specific interpretation here. When
2839  possible/practical, f's error state gets updated with a
2840  human-readable description of the problem.
2841 
2842  ACHTUNG: all pending checking state is cleaned if this function
2843  fails for any reason other than basic argument validation. This
2844  means any queued files or tags need to be re-applied if the
2845  client wants to try again. That is somewhat of a bummer, but this
2846  behaviour is the only way we can ensure that then the pending
2847  checkin state does not get garbled on a second use. When in doubt
2848  about the state, the client should call fsl_checkin_discard() to
2849  clear it before try to re-commit. (Potential TODO: add a
2850  success/fail state flag to the checkin state and only clean up on
2851  success? OTOH, since something in the state likely caused the
2852  problem, we might not want to do that.)
2853 
2854  This operation does all of its db-related work i a transaction,
2855  so it rolls back any db changes if it fails.
2856 
2857  Some of the more notable, potentially not obvious, error
2858  conditions:
2859 
2860  - Trying to commit against a closed leaf: FSL_RC_MISUSE
2861 
2862  - An empty/NULL user name or commit message, or no files were
2863  selected which actually changed: FSL_RC_RANGE. In these cases
2864  f's error state describes the problem.
2865 
2866  - Some resource is not found (e.g. an expected RID/UUID could not
2867  be resolved): FSL_RC_NOT_FOUND. This would generally indicate
2868  some sort of data consistency problem. i.e. it's quite possible
2869  very bad if this is returned.
2870 
2871  BUGS:
2872 
2873  - The new leaf of the branch is not being properly
2874  calculated/updated somewhere, but not yet sure where. If this
2875  function recalculates all leaves then only the current checkout
2876  version (before this call) is marked as a leaf, otherwise all
2877  checkin versions made by this function retain their is-a-leaf
2878  status. When the checkin in synched via fossil(1) the artifact
2879  arrives and crosslinks just fine, and a 'fossil rebuild' fixes
2880  this locally, both of which indicate that the problem is probably
2881  somewhere in our crosslinking (or similar), as opposed to the
2882  manifest's metadata. i've been through fossil(1)'s checkin and
2883  crosslinking implementations backwards and forwards and have not
2884  yet found the missing/broken piece.
2885 
2886  @see fsl_checkin_file_enqueue()
2887  @see fsl_checkin_file_dequeue()
2888  @see fsl_checkin_discard()
2889  @see fsl_checkin_T_add()
2890 */
2892  fsl_id_t * newRid, fsl_uuid_str * newUuid);
2893 
2894 /**
2895  Works like fsl_deck_T_add(), adding the given tag information to
2896  the pending checkin state. Returns 0 on success, non-0 on
2897  error. A checkin may, in principal, have any number of tags, and
2898  this may be called any number of times to add new tags to the
2899  pending commit. This list of tags gets cleared by a successful
2900  fsl_checkin_commit() or by fsl_checkin_discard().
2901 
2902  @see fsl_checkin_file_enqueue()
2903  @see fsl_checkin_file_dequeue()
2904  @see fsl_checkin_commit()
2905  @see fsl_checkin_discard()
2906 */
2907 FSL_EXPORT int fsl_checkin_T_add( fsl_cx * f, fsl_tag_type tagType,
2908  fsl_uuid_cstr uuid, char const * name,
2909  char const * value);
2910 
2911 
2912 
2913 /**
2914  Tries to determine the [filename.fnid] value for the given
2915  filename. Returns a positive value if it finds one, 0 if it
2916  finds none, and some unspecified negative value(s) for any sort
2917  of error. filename must be a normalized, relative filename (as it
2918  is recorded by a repo).
2919 */
2920 FSL_EXPORT fsl_id_t fsl_repo_filename_fnid( fsl_cx * f, char const * filename );
2921 
2922 
2923 /**
2924  Imports content to f's opened repository's BLOB table using a
2925  client-provided input source. f must have an opened repository
2926  db. inFunc is the source of the data and inState is the first
2927  argument passed to inFunc(). If inFunc() succeeds in fetching all
2928  data (i.e. if it always returns 0 when called by this function)
2929  then that data is inserted into the blob table _if_ no existing
2930  record with the same SHA1 hash is already in the table. If such a
2931  record exists, it is assumed that the content is identical and
2932  this function has no side-effects vis-a-vis the db in that case.
2933 
2934  If rid is not NULL then the BLOB.RID record value (possibly of an
2935  older record!) is stored in *rid. If uuid is not NULL then the
2936  BLOB.UUID record value is stored in *uuid and the caller takes
2937  ownership of those bytes, which must eventually be passed to
2938  fsl_free() to release them.
2939 
2940  rid and uuid are only modified on success and only if they are
2941  not NULL.
2942 
2943  Returns 0 on success, non-0 on error. For errors other than basic
2944  argument validation and OOM conditions, f's error state is
2945  updated with a description of the problem. Returns FSL_RC_MISUSE
2946  if either f or inFunc are NULL. Whether or not inState may be
2947  NULL depends on inFunc's concrete implementation.
2948 
2949  Be aware that BLOB.RID values can (but do not necessarily) change
2950  in the life of a repod db (via a rebuild, a full re-clone, or
2951  similar, or simply when referring to different clones of the same
2952  repo). Thus clients should always store the full UUID, as opposed
2953  to the RID, for later reference. RIDs should, in general, be
2954  treated as session-transient values. That said, for purposes of
2955  linking tables in the db, the RID is used exclusively (clients
2956  are free to link their own extension tables using UUIDs, but
2957  doing so has a performance penalty comared to RIDs). For
2958  long-term storage of external links, and to guaranty that the
2959  data be usable with other copies of the same repo, the UUID is
2960  required.
2961 
2962  Note that Fossil may deltify, compress, or otherwise modify
2963  content on its way into the blob table, and it may even modify
2964  content long after its insertion (e.g. to make it a delta against
2965  a newer version). Thus clients should normally never try
2966  to read back the blob directly from the database, but should
2967  instead read it using fsl_content_get().
2968 
2969 
2970  Maintenance reminder: this is basically just a glorified form of
2971  the internal fsl_content_put(). Interestingly, fsl_content_put()
2972  always sets content to public (by default - the f object may
2973  override that later). It is not yet clear whether this routine
2974  needs to have a flag to set the blob private or not. Generally
2975  speaking, privacy is applied to fossil artifacts, as opposed to
2976  content blobs.
2977 
2978  @see fsl_repo_import_buffer()
2979 */
2980 FSL_EXPORT int fsl_repo_import_blob( fsl_cx * f, fsl_input_f inFunc, void * inState,
2981  fsl_id_t * rid, fsl_uuid_str * uuid );
2982 
2983 /**
2984  A convenience form of fsl_repo_import_blob(), equivalent to:
2985 
2986  @code
2987  fsl_repo_import_blob(f, fsl_input_f_buffer, bIn, rid, uuid )
2988  @endcode
2989 
2990  except that (A) bIn is const in this call and non-const in the
2991  other form (due to cursor traversal requirements) and (B) it
2992  returns FSL_RC_MISUSE if pIn is NULL.
2993 */
2994 FSL_EXPORT int fsl_repo_import_buffer( fsl_cx * f, fsl_buffer const * bIn,
2995  fsl_id_t * rid, fsl_uuid_str * uuid );
2996 
2997 
2998 #if 0
2999 /**
3000  NOT YET IMPLEMENTED - just thinking out loud here.
3001 */
3002 struct fsl_repo_open_opt {
3003 
3004  /**
3005  Name of the target directory, which must already
3006  exist.
3007  */
3008  char const * targetDir;
3009 
3010  /**
3011  0 = error on overwrite,
3012  >0 = overwrite
3013  <0 = keep existing files
3014  */
3015  int fileOverwritePolicy;
3016  /**
3017  0 = error if already exists
3018  >0 = overwrite file and/or contents
3019  */
3020  int dbOverwritePolicy;
3021 };
3022 typedef struct fsl_repo_open_opt fsl_repo_open_opt;
3023 
3024 /**
3025  NOT YET IMPLEMENTED - just thinking out loud here.
3026 
3027  - Requires that f have an opened repository db and no opened checkout.
3028 
3029  - Creates/re-uses a .fslckout DB in the dir opt->targetDir, which
3030  must exist or FSL_RC_NOT_FOUND is returned. If
3031  opt->dbOverwritePolicy is false then it fails with
3032  FSL_RC_ALREADY_EXISTS if that directory already contains a checkout
3033  db.
3034 
3035  Pending:
3036 
3037  - factor out the find-checkout-db-file code into its own routine so
3038  that we can use it here without having to call the
3039  fsl_checkout_open_dir() (which would close/reopen the repo,
3040  invalidating any handles to it).
3041 
3042  - Refactor fsl_checkout_open_dir() into the additional function
3043  fsl_checkout_open_db().
3044 */
3045 FSL_EXPORT int fsl_repo_open_checkout( fsl_cx * f, fsl_repo_open_opt const * opt );
3046 #endif
3047 
3048 
3049 #if defined(__cplusplus)
3050 } /*extern "C"*/
3051 #endif
3052 #endif
3053 /* NET_FOSSIL_SCM_FSL_CONTENT_H_INCLUDED */
fsl_catype_t
An enumeration of the types of control artifacts used by Fossil.
Definition: fossil-core.h:1548
char * name
Filename of the A-card.
fsl_cx * f
The associated Fossil context.
Parameters for fsl_checkin_commit().
void const * allocStamp
A marker which tells fsl_deck_finalize() whether or not fsl_deck_malloc() allocated this instance (in...
Indicates that a file was modified in some unspecified way.
Callback state for use with fsl_repo_extract_f() implementations to stream a given version of a repos...
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_CATYPE_ATTACHMENT) deck.
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. ...
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...
char * C
The 'C' (comment) card.
int(* fsl_repo_extract_f)(fsl_repo_extract_state const *xstate)
A callback type for use with fsl_repo_extract().
fsl_list J
The 'J' card specifies changes to "value" of "fields" in tickets (FSL_CATYPE_TICKET).
FSL_EXPORT const fsl_branch_opt fsl_branch_opt_empty
fsl_uuid_str src
UUID of the file being attached via the A-card.
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...
char isPrivate
If true, the checkin will be marked as private, otherwise it will be marked as private or public...
FSL_EXPORT void fsl_deck_finalize(fsl_deck *deck)
Frees all memory owned by deck (see fsl_deck_clean()).
The main Fossil "context" type.
FSL_EXPORT void fsl_checkin_discard(fsl_cx *f)
Discards any state accumulated for a pending checking, including any files queued via fsl_checkin_fil...
FSL_EXPORT int fsl_deck_K_set(fsl_deck *mf, fsl_uuid_cstr uuid)
Semantically identical fsl_deck_B_set() but sets the K-card.
The "add tag" indicator, a.k.a.
fsl_double_t mtime
The julian time of the branch.
FSL_EXPORT int fsl_repo_import_buffer(fsl_cx *f, fsl_buffer const *bIn, fsl_id_t *rid, fsl_uuid_str *uuid)
A convenience form of fsl_repo_import_blob(), equivalent to:
FSL_EXPORT int fsl_checkout_changes_visit(fsl_cx *f, fsl_id_t vid, char doChangeScan, fsl_checkout_changes_f visitor, void *state)
Compares the changes of f's local checkout against repository version vid (checkout version if vid is...
fsl_int64_t fsl_time_t
The type used to represent type values.
FSL_EXPORT int fsl_repo_extract(fsl_cx *f, fsl_id_t vid, fsl_repo_extract_f callback, void *callbackState)
Extracts the contents of the given checkin version ID, sending the appropriate version of each file's...
char * name
The tag's name.
char const * message
The commit message.
fsl_list M
List of UUIDs (fsl_uuid_str) in a cluster ('M' cards).
fsl_tag_ids
Hard-coded IDs used by the 'tag' table of repository DBs.
fsl_buffer content
This is part of an optimization used when parsing fsl_deck instances from source text.
FSL_EXPORT int fsl_content_blob(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_id_t versionRid
RID of the checkin version for this file.
fsl_uuid_str baseline
UUID of the baseline for the cherrypick.
char const * bgColor
If this->branch is not NULL, this is applied as its "bgcolor" propagating property.
Sentinel value for use with constructors/initializers.
FSL_EXPORT int fsl_deck_D_set(fsl_deck *mf, fsl_double_t date)
Sets mf's D-card as a Julian Date value.
FSL_EXPORT int fsl_card_is_legal(fsl_catype_t t, char card)
This function is a programmatic interpretation of this table:
FSL_EXPORT char fsl_rid_is_leaf(fsl_cx *f, fsl_id_t rid)
Returns non-0 (true) if the checkin with the given rid is a leaf, 0 (false) if not.
char * tgt
Name of event or UUID of ticket or wiki page to which the attachment applies.
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 const fsl_checkin_opt fsl_checkin_opt_empty
Empty-initialized fsl_checkin_opt instance, intended for use in copy-constructing.
FSL_EXPORT int fsl_deck_unshuffle(fsl_deck *d, char calculateRCard)
Prepares the given deck for output by ensuring that cards which need to be sorted are sorted...
char const * comment
Optional comment (may be NULL).
A container for storing generic error state.
Definition: fossil-util.h:692
FSL_EXPORT int fsl_deck_F_add2(fsl_deck *mf, fsl_card_F *t)
Adds the given file instance to the given deck.
fsl_list list
A list of 'F' (file) cards.
fsl_list P
List of UUIDs of parents ('P' cards).
FSL_EXPORT const fsl_deck fsl_deck_empty
Initialized-with-defaults fsl_deck structure, intended for copy initialization.
fsl_deck * next
To be used for a manifest cache.
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_checkin_commit(fsl_cx *f, fsl_checkin_opt const *opt, fsl_id_t *newRid, fsl_uuid_str *newUuid)
Do not use - under construction/testing.
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.
char const * user
The user name for the checkin.
fsl_uuid_str K
UUID for the 'K' (ticket) card.
unsigned char flags
For internal use only.
#define FSL_EXPORT
Definition: fossil-config.h:19
FSL_EXPORT int fsl_deck_crosslink(fsl_deck *d)
Runs postprocessing on the Control Artifact represented by d.
FSL_EXPORT char fsl_uuid_is_shunned(fsl_cx *f, fsl_uuid_cstr zUuid)
Return true if the given artifact ID should is listed in f's shun table, else false.
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.
DB string tagname='bgcolor'.
char const * fsl_uuid_cstr
The const counterpart of fsl_uuid_str.
Definition: fossil-util.h:92
FSL_EXPORT int fsl_checkin_T_add(fsl_cx *f, fsl_tag_type tagType, fsl_uuid_cstr uuid, char const *name, char const *value)
Works like fsl_deck_T_add(), adding the given tag information to the pending checkin state...
Generic list container type.
Definition: fossil-util.h:150
fsl_buffer const * content
Holds the full, undelta'd/uncompressed content of fc's file record.
char * name
Name of the file.
Indicates that a file is missing from the local checkout.
char * field
The ticket field to update.
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.
char * value
The value for the field.
DB: tag.tagname='comment'.
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 int fsl_checkout_file_rm(fsl_cx *f, char relativeToCwd, char const *zFilename, char recurseDirs)
The converse of fsl_checkout_file_add(), this queues a file for removal from the current checkout...
fsl_id_t rid
DB repo.blob.rid value.
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().
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 fsl_deck_required_cards_check(fsl_deck const *d, fsl_error *err)
Returns true (non-0) if d contains data for all _required_ cards, as determined by the value of d->ty...
char * L
The 'L' (wiki name/title) card.
fsl_catype_t type
Specifies the the type (or eventual type) of this artifact.
FSL_EXPORT void fsl_card_F_free(fsl_card_F *f)
Calls fsl_card_F_clean(t) and then passes t to fsl_free().
DB: tag.tagname='date'.
FSL_EXPORT int fsl_repo_import_blob(fsl_cx *f, fsl_input_f inFunc, void *inState, fsl_id_t *rid, fsl_uuid_str *uuid)
Imports content to f's opened repository's BLOB table using a client-provided input source...
char * U
The U (user) card.
FSL_EXPORT char fsl_tag_prefix_char(fsl_tag_type t)
Returns one of '-', '+', or '*' for a valid input parameter, 0 for any other value.
fsl_file_perm_t
Filesystem-level permissions flags supported by fossil Manifests.
Definition: fossil-core.h:431
The "cancel tag" indicator, a.k.a.
fsl_deck * baseline
Baseline manifest corresponding to this->B.
int type
0==invalid, negative==backed out, positive=cherrypicked.
fsl_tag_type type
The type of tag.
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_wiki_save_mode_t
A helper type for use with fsl_wiki_save(), intended primarily to help client-side code readability s...
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 fsl_card_F * fsl_card_F_malloc(char const *name, fsl_uuid_cstr uuid, fsl_file_perm_t perm, char const *oldName)
Allocates a new fsl_card_F instance for use with fsl_deck_F_add2().
char * fsl_uuid_str
fsl_uuid_str and fsl_uuid_cstr are "for documentation and readability purposes" typedefs used to deno...
Definition: fossil-util.h:85
char * value
The tag's value.
FSL_EXPORT int fsl_deck_parse(fsl_deck *d, fsl_buffer *src)
Parses src as Control Artifact content and populates d with it.
Represents a J card in a Ticket Control Artifact.
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_E_set(fsl_deck *mf, fsl_double_t date, fsl_uuid_cstr uuid)
Sets the E-card in the given deck.
fsl_int32_t fsl_id_t
fsl_id_t is a signed integer type used to store database record IDs.
int(* fsl_deck_xlink_f)(fsl_cx *f, fsl_deck const *d, void *state)
A callback interface for manifest crosslinking, so that we can farm out the updating of the event tab...
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 const fsl_card_T fsl_card_T_empty
Defaults-initialized fsl_card_T instance.
fsl_id_t basisRid
The checkin RID from which the branch should originate.
FSL_EXPORT int fsl_checkin_file_enqueue(fsl_cx *f, char const *zName, char relativeToCwd)
Don't use this yet - the whole checkin-queue mechanism is an experiment at this point.
fsl_uuid_str uuid
UUID of the artifact this tag is tagging.
fsl_file_perm_t perm
File permissions.
FSL_EXPORT const fsl_card_Q fsl_card_Q_empty
Empty-initialized fsl_card_Q struct.
Represents a tag in a Manifest or Control Artifact.
FSL_EXPORT void fsl_deck_init(fsl_cx *cx, fsl_deck *d, fsl_catype_t type)
Must be called to initialize a newly-created/allocated deck instance.
fsl_buffer W
The W (wiki content) card.
DB: tag.tagname='closed'.
FSL_EXPORT int fsl_deck_F_foreach(fsl_deck *d, char includeBaseline, fsl_card_F_visitor_f cb, void *visitorState)
For each F-card in d, cb(card,visitorState) is called.
int deltaPolicy
Whether to allow (or try to force) a delta manifest or not.
char append
If true, the new value should be appended to any existing one with the same key, else it will replace...
Indicates that a file was modified as the result of an integrate-merge.
char const * messageMimeType
The optional mime type for the message.
FSL_EXPORT int fsl_content_get(fsl_cx *f, fsl_id_t blobRid, fsl_buffer *tgt)
Functionally similar to fsl_content_blob() but does a lot of work to ensure that the returned blob is...
FSL_EXPORT int fsl_checkin_file_dequeue(fsl_cx *f, char const *zName, char relativeToCwd)
The opposite of fsl_checkin_file_enqueue(), then removes the given file or directory name from f's ch...
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.
int integrate
Tells the checkin to close merged-in branches (merge type of 0).
FSL_EXPORT void fsl_card_F_clean(fsl_card_F *t)
Frees up any memory owned by t and clears out t's state, but does not free t.
A general-purpose buffer class, analog to Fossil v1's Blob class, but it is not called fsl_blob to av...
Definition: fossil-util.h:632
fsl_uuid_str target
UUID of the target of the cherrypick.
fsl_card_F const * fc
The F-card being iterated over.
fsl_uuid_str uuid
UUID of the underlying blob record for the file.
FSL_EXPORT char fsl_checkin_file_is_enqueued(fsl_cx *f, char const *zName, char relativeToCwd)
Returns true (non-0) if the file named by zName is in f's current file checkin queue.
char const * name
The name of the branch.
char const * user
User name for the branch.
FSL_EXPORT const fsl_card_J fsl_card_J_empty
Empty-initialized fsl_card_J struct.
fsl_error error
For propagating error state through certain parts of the API.
FSL_EXPORT fsl_card_J * fsl_card_J_malloc(char isAppend, char const *field, char const *value)
Allocates a new J-card record instance.
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.
Largest tag ID reserved for internal use.
fsl_id_t fileRid
File-level blob.rid for fc.
FSL_EXPORT int fsl_tag_rid(fsl_cx *f, fsl_tag_type tagType, fsl_id_t artifactRidToTag, char const *tagName, char const *tagValue, char const *userName, fsl_double_t mtime, fsl_id_t *newId)
Adds a control record to f's repositoriy that either creates or cancels a tag.
FSL_EXPORT fsl_card_Q * fsl_card_Q_malloc(int type, fsl_uuid_cstr target, fsl_uuid_cstr baseline)
Allocates a new cherrypick record instance.
FSL_EXPORT int fsl_delta_src_id(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...
struct fsl_deck::@2 A
The 'A' (attachment) card.
FSL_EXPORT int fsl_checkout_file_add(fsl_cx *f, char relativeToCwd, char const *zFilename)
Adds the given filename to the current checkout vfile list of files as a to-be-added file...
void * state
Client state passed to fsl_repo_extract().
DB: tag.tagname='parent'.
char const * dumpManifestFile
Tells fsl_checkin_commit() to dump the generated manifest to this file.
fsl_list Q
'Q' (cherry pick) cards.
Represents one file entry in a Manifest/Control Artifact (i.e., a checkin version).
FSL_EXPORT fsl_deck * fsl_deck_malloc()
Allocates a new fsl_deck instance.
fsl_double_t D
The 'D' (date) card, in Julian format.
FSL_EXPORT fsl_card_T * fsl_card_T_malloc(fsl_tag_type tagType, fsl_uuid_cstr uuid, char const *name, char const *value)
Allocates a new fsl_card_T instance.
int(* fsl_input_f)(void *state, void *dest, fsl_size_t *n)
Generic interface for streaming in data.
Definition: fossil-util.h:298
char const * branch
Don't use this yet - it is not yet tested all that well.
int(* fsl_deck_visitor_f)(fsl_cx *f, fsl_deck const *d, void *state)
Generic callback interface for visiting decks.
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 and it is not lo...
Indicates that fsl_wiki_save() must only allow the update of an existing page, and will not create a ...
DB: tag.tagname='user'.
FSL_EXPORT void fsl_card_J_free(fsl_card_J *cp)
Frees a J-card record created by fsl_card_J_malloc().
fsl_list T
List of 'T' (tag) cards.
FSL_EXPORT int fsl_deck_load_rid(fsl_cx *f, fsl_deck *d, fsl_id_t rid, fsl_catype_t type)
Loads the content from given rid and tries to parse it as a Fossil artifact.
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...
char const * bgColor
Optional background color for the fossil(1) HTML timeline view.
DB: tag.tagname='branch'.
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_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...
FSL_EXPORT int fsl_deck_baseline_fetch(fsl_deck *d)
Loads the baseline manifest specified in d->B.uuid.
Indicates that a file was added.
FSL_EXPORT int fsl_repo_dir_names(fsl_cx *f, fsl_id_t rid, fsl_list *tgt, char addSlash)
Fetches the list of all directory names for a given record id or (if rid is negative) the whole repo ...
FSL_EXPORT const fsl_card_F fsl_card_F_empty
Empty-initialized fsl_card_F instance, intended for use in copy-constructing.
DB: tag.tagname='private'.
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_deck_U_set(fsl_deck *mf, char const *userName, fsl_int_t len)
Semantically identical fsl_deck_B_set() but sets the U-card.
FSL_EXPORT int fsl_card_F_compare(fsl_card_F const *lhs, fsl_card_F const *rhs)
Given two F-card instances, this function compares their names (case-insensitively).
double fsl_double_t
fsl_double_t is the double type used by the library.
Indicates that a file was added as the result of a merge.
char * N
The 'N' (content mime type) card.
fsl_cx * f
The Fossil context responsible for this deck.
Indicates that a file was removed.
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 void fsl_card_Q_free(fsl_card_Q *cp)
Frees a cherrypick record created by fsl_card_Q_malloc().
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_tag_type
Artifact tag types used by the Fossil framework.
char externalStrings
An internal optimization.
A "deck" stores (predictably enough) a collection of "cards." Cards are constructs embedded within Fo...
FSL_EXPORT char 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 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 char 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.
Holds options for use with fsl_branch_create().
FSL_EXPORT int fsl_checkout_changes_scan(fsl_cx *f)
Sets up the vfile table in f's opened checkout db and scans the checkout root directory's contents fo...
fsl_checkout_change_t
Change-type flags for use with fsl_checkout_changes_visit() and friends.
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.
char * R
The R-card holds an MD5 hash which is calculated based on the names, sizes, and contents of the files...
struct fsl_deck::@3 B
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_J_add(fsl_deck *mf, char 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...
char const * closeBranch
If this is not NULL then the committed manifest will include a tag which closes the branch...
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 void fsl_deck_clean(fsl_deck *deck)
Frees all resources belonging to the given deck's members (including its parents, recursively)...
char * priorName
Previous name if the file was renamed, else NULL.
int calcRCard
Whether or not to calculate an R-card.
FSL_EXPORT int fsl_deck_M_add(fsl_deck *mf, fsl_uuid_cstr uuid)
Adds the given UUID as an M-card entry.
fsl_double_t julian
The 'E' card's date in Julian Day format.
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 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"...
char isPrivate
If true, the branch will be marked as private.
FSL_EXPORT int fsl_checkout_filename_check(fsl_cx *f, char relativeToCwd, char const *zOrigName, fsl_buffer *pOut)
Given a fsl_cx with an opened checkout, and a filename, this function canonicalizes zOrigName to a fo...
FSL_EXPORT char fsl_deck_has_required_cards(fsl_deck const *d)
Equivalent to fsl_deck_required_cards_check(d, NULL);.
int(* fsl_checkout_changes_f)(void *state, fsl_checkout_change_t change, char const *filename, char const *origName)
A typedef for visitors of checkout status information via fsl_checkout_changes_visit().
Indicates that a file was renamed.
FSL_EXPORT void fsl_card_T_free(fsl_card_T *t)
Calls fsl_card_T_clean(t) and then passes t to fsl_free().
fsl_int_t cursor
An internal cursor into this->list, used primarily for properly traversing the file list in delta man...
Represents a Q card in a Manifest or Control Artifact.
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_sym(fsl_cx *f, fsl_deck *d, char const *symbolicName, fsl_catype_t type)
A convenience form of fsl_deck_load_rid() which uses fsl_sym_to_rid() to convert symbolicName into an...
FSL_EXPORT int fsl_deck_T_add(fsl_deck *mf, fsl_tag_type tagType, fsl_uuid_cstr uuid, char const *name, char const *value)
Adds a new T-card (tag) entry to the given deck.
Indicates that fsl_wiki_save() must allow both the update and creation of pages.
DB: tag.tagname='hidden'.
Indicates that fsl_wiki_save() must only allow the creation of a new page, and must fail if such an e...
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_deck_F_add(fsl_deck *mf, char const *name, fsl_uuid_cstr uuid, fsl_file_perm_t perm, char const *oldName)
Adds a new F-card to the given deck.
Sentinel placeholder value.
FSL_EXPORT int fsl_deck_save(fsl_deck *d, char isPrivate)
Saves the given deck into f's repository database as new control artifact content.
int(* fsl_card_F_visitor_f)(fsl_card_F const *fc, void *state)
Callback type for use with fsl_deck_F_foreach() and friends.
struct fsl_deck::@5 F
The 'F' (file) card container.
fsl_uuid_str uuid
Gets set by fsl_deck_parse() to the hash/UUID of the manifest it parsed.
fsl_double_t julianTime
Time of the checkin.
int(* fsl_output_f)(void *state, void const *src, fsl_size_t n)
Generic interface for streaming out data.
Definition: fossil-util.h:275
FSL_EXPORT int fsl_deck_output(fsl_deck const *mf, fsl_output_f out, void *outputState, fsl_error *errOut)
Renders the given control artifact's contents to the given output function and calculates any cards w...
FSL_EXPORT int fsl_deck_T_add2(fsl_deck *mf, fsl_card_T *t)
Adds the given tag instance to the given manifest.
struct fsl_deck::@4 E
The 'E' (event) card.
FSL_EXPORT int fsl_tag_sym(fsl_cx *f, fsl_tag_type tagType, char const *symToTag, char const *tagName, char const *tagValue, char const *userName, fsl_double_t mtime, fsl_id_t *newId)
Equivalent to fsl_tag_rid() except that it takes a symbolic artifact name in place of an artifact ID ...
DB: tag.tagname='cluster'.
Indicates that a file was modified as the result of a merge.
The "propagating tag" indicator.
Indicates that a file was added as the result of an integrate-merge.