#include <LogBookNote.h>
class LogBookNote
{
public:
typedef struct _NoteText {
int s_id;
int s_runId; // Associated run.
int s_authorId;
time_t s_noteTime;
std::string s_contents;
} NoteText, *pNoteText;
typedef struct _ImageInfo {
std::string s_filename;
size_t s_offset;
} ImageInfo, *pImageInfo;
typedef struct _NoteImage {
int s_id;
int s_noteId;
int s_noteOffset;
std::string s_originalFilename;
size_t s_imageLength;
void* s_pImageData;
} NoteImage, *pNoteImage;
public:
LogBookNote(CSqlite& db, int noteId);
LogBookRun* getAssociatedRun(CSqlite& db) const;
const NoteText& getNoteText() const;
size_t imageCount() const;
const NoteImage& operator[](int n) const;
std::string substituteImages();
static LogBookNote* create(
CSqlite& db, LogBookRun* run, const char* string,
LogBookPerson* pPerson,
const std::vector<ImageInfo>& images
);
static std::vector<int> listRunNoteIds(CSqlite& db, int runId);
static std::vector<int> listNonRunNotes(CSqlite& db);
static std::vector<LogBookNote*> getAllNotes(CSqlite& db);
static std::vector<LogBookNote*> getRunNotes(CSqlite& db, int runId);
static std::vector<LogBookNote*> getNonRunNotes(CSqlite& db);
std::string exportImage(const NoteImage& image);
};
... -I$DAQINC -L$DAQLIB -lLogbook -Wl,-rpath=$DAQLIB
Instances of LogBookNote encapsulate data
in the database stored for a single note. Notes are considered to be
a soup of rich text in Markdown format
(see https://https://www.markdownguide.org/).
A note has metadata that consists of an author, a timestamp that
indicates when it was submitted to the database and optionally
a run with which it's associated.
As the Markdown syntax supports image file references, and we want our logbook databases to be self-contained, when a note is submitted, it is the authoring software's responsibility to submit the markdown along with a set of image filenames and the byte offset into the note text at which the image file reference begins. (the byte offset of the ! in e.g. ).
Methods are provided to obtain the note text, re-exporting the images into the logbook temporary directory and fixing up image references so that they work properly. Image formats are not restricted by this software but only by the software used to view renderings of the markdown code (e.g. the web-browser for HTML renderings or acceptable LaTeX image formats for PDF).
It is important to note that this class's rendering is limited to provding fixed-up markdown text. The problem of rendering this markdown into PDF or HTML and viewing it is pushed out onto user level software (e.g. lg_print or lg_browse). Reasonable well developed Tcl support software has been developed and will be described in pages in the 3tcl reference section.
Some of the methods described here are provide to hide implementation
details from the LogBook class and not intended
for general use. These will be pointed out but documented for
programmers of the logbook support software and to allow for
use cases not-foreseen.
LogBookNote(CSqlite& db, int noteId);
Not intended for general use. Locates the note with the
primary key noteId from the
database indicated by db and
loads the data associated with that note, wrapping it in a
newly constructed LogBookNote instance.
This constructor is intended to hide note implementation details
from the LogBook API class.
const LogBookRun* getAssociatedRun(CSqlite& db);
If this note in the database db,
the data associated with that run is wrapped into a new
LogBookRun object and a pointer
to that object returned. As the
LogBookRun object is a dynamically
created object, when it is no longer needed your
program must destroy it with delete.
const const NoteText& getNoteText();
Returns a NoteText reference
to the data that describe the note. See
DATA TYPES for a description of the
NoteText data structure.
const size_t imageCount();
Returns the number of image referenes that are claimed to be embedded in to the note Markdown text.
const const NoteImage& operator(int n);
Returns information about the n'th
image reference in the note text. The
NoteImage data structure
is described in DATA TYPES. If
n is out of range of the number
of images actually associated with the note text,
a std::out_of_range exception is
thrown.
std::string substituteImages();
Iterates over the images associated with the note. For each image reference, the image data in the database is exported into a file in the logbook temporary directory, the image reference in the logbook text is then fixed up to properly reference the exported image.
The return value is the text of the note after all images have been exported and their references fixed up. Note that the original text in the database is not modified.
LogBook::Exception is thrown if the
byte offset of an image reference does not point to a valid
markdown image reference. Note that image export does not
imply that the data are necessarily a valid image format.
The code just exports the bytes it has.
static LogBookNote* create(CSqlite& db, LogBookRun* run, const char* string, LogBookPerson* pPerson, const std::vector<ImageInfo>& images);
This method is not intended for general use.
It creates a new note in the database indicated by
db. run is
a pointer to a run encapsulation for a run that will be associated
with the note. If there is no associated run, this should be
a nullptr. string are
the contents of the note. pPerson
is a pointer to an encapsulation of the person who is authoring
the note. images are a vector
of image files paths and where their references appear in the
string. The
ImageInfo struct is documented in
DATA TYPES
On success a new note has been created and a new
LogBookNote wrapped around its data.
A pointer to that note is then returned. The
LogBookNote object is dynamically
created and, therefore, when no longer needed must be
destroyed with delete/
static std::vector<int> listRunNoteIds(CSqlite& db, int runId);
Not intended for general use. Given a logbook database;
db and the primary key of a run
in that database, returns a vector of all of the note ids
associated with that run.
static std::vector<int> listNonRunNotes(CSqlite& db);
Not for general use. Given a logbook database;
db returns the ids of all notes
that are not associated with any run.
static std::vector<LogBookNote*> getAllNotes(CSqlite& db);
Not intended for general use.
Given a logbook database; db,
returns a vector of pointers to
LogBookNote encapsulations of all notes.
The LogBookNote objects are all dynamically
created so when no longer needed, the program must destroy them
with delete to avoid resourcde leaks.
static std::vector<LogBookNote*> getRunNotes(CSqlite& db, int runId);
Not intended for general use. Given a
database db connection object
and the primary key of a run; runId,
for each note associated with that run, encapsulates it in
a LogBookRun object. A vector containing
pointer to all those objects is then returned.
the objects are dynamically created and must be destroyed
using delete when no longer needed.
static std::vector<LogBookNote*> getNonRunNotes(CSqlite& db);
Given a logbook database; db,
encapsulates all notes that are not associated with a run
in LogBookNote objects and return a
vector of pointers to those objects.
Since the objects are dynamically created and must be destroyed
using delete when no longer needed.
std::string exportImage(const NoteImage& image);
Given image information, exports the image into a file
in the logbook image diretory and returs a full path to the
image. This is not intended for general use. Normally it's
used internally as part of
substituteImages, however it turned
out to be useful by they Python bindings API.
LogBookNote exports several data types.
This data type encapsulates the raw note text and metadata.
s_idThe primary key of the note.
s_runIdIf there is an associated run, this is it's primary key. If not, this value is 0 which is an invalid primary key value.
s_authoriIdThe primary key of the person who authored the note.
s_noteTimeThe time(2) at which the note was entered in the database.
s_contentsThe text of the note itself.
This struct provides information about images referenced in the note text. This struct is used to specify files to capture into the database.
s_filenameThe original file path specifying an image that is to be loaded into the database.
s_offsetThe byte offset of the ! that is the first character of the reference to this image in the note text.
This struct captures the data stored in the database for images that are captured in the database.
s_idThe primary key of the image in its table.
s_noteIdThe primary key of the note that needs this image.
s_noteOffsetThe offset in the note text at which the link referencing this note begins.
The original filename of the note. This is normally used to help construct the name of the exportefile.
s_imageLengthNumber of bytes of image data.
s_pImageDataPointer to image data; that is the original contents of the file.