/*! \page mod_bbpage The Blackboard

\section bb_overview Overview

The blackboard plays a critical role in allowing modules to communicate. 
A module can post data to the blackboard so that subsequent modules can see its results. 
It can also query the blackboard to see what previous modules have posted. 

Conceptually, the blackboard is borrowed from artificial intelligence applications in which knowledge sources (the modules) share information to collaboratively solve a problem (disk image analysis).
In practice, the framework's blackboard is a collection of <em>artifacts</em>, each associated with a file, and each consisting of a collection of name-value pairs called <em>attributes</em>. 
Examples of artifacts include web browser bookmarks (with URL and date attributes) and GPS track points (with geo-coordinates and date attributes).
The analysis of any given file in an image may produce few artifacts and attributes or a wealth of artifacts and attributes, depending on the modules in use and the files themselves.

Note that the blackboard exists in both TSK Framework (C++) and the Java bindings for TSK Core. This page is the overview for both programming languages. 
The C++ source code is linked here, but unless otherwise noted, the Java bindings provide similar or identical functionality.

\section bb_access Accessing the Blackboard

C++ modules access the blackboard by getting a reference to a TskBlackboard object from TskServices. 

Java modules can obtain blackboard access from either the <em><b>SleuthkitCase</b></em> object or the <em><b>Content</b></em> object. 

\section bb_art_types Artifact Types

Every artifact has a type, in addition to its collection of attributes.  
Artifact type definitions consist of a unique type name and a display name that does not need to be unique, but should be human-readable. 
The framework assigns a unique integer ID to each artifact type.  

\subsection bb_art_types_std Standard Artifact Types

The framework predefines a number of artifact types that are generally important to digital forensics work.  
For example, each file typically has a #TSK_GEN_INFO artifact that groups attributes that pertain to the file (e.g., file metadata), but are not necessarily related to each other in any other way. 
 
Please refer to the #TSK_ARTIFACT_TYPE enum for a full listing of the standard artifact types.   

\subsection bb_art_types_add Defining New Artifact Types

If you need to create artifacts of a type that does not already exist in the framework, you can define your own artifact type.  
The framework comes with a TskDBBlackboard class that implements the TskBlackboard interface. 
Simply call the TskBlackboard::addArtifactType() function, supplying the desired type name and display name.  
The TskDBBlackboard version of this function will create the artifact type if it doesn't already exist, and will return the integer ID for the type. 


\section bb_attr_types Attribute Types

An attribute is a name-value pair, where the name indicates the type of the attribute. 
Like artifact type definitions, attribute type definitions consist of a unique type name and a display name that does not need to be unique, but should be human-readable.
The framework assigns a unique integer ID to each attribute type. 

Attributes also have an optional context field that can be set to a string of your choosing. 

\subsection bb_attr_types_std Standard Attribute Types

The framework predefines standard attribute types that complement the standard artifact types, and are likewise generally important to digital forensics work.   
For example, a module that computes the entropy of a file could record the result of its calculation by adding a standard #TSK_ENTROPY attribute to the #TSK_GEN_INFO artifact of the file.

Please refer to the #TSK_ATTRIBUTE_TYPE enum for a full listing of the standard attribute types.   

\subsection bb_attr_types_add Creating Attribute Types

You can create new attribute types using a similar mechanism to that used to create new artifact types.
Call the TskBlackboard::addAttributeType() function, supplying the desired type name and display name.  
The TskDBBlackboard version of this function will create the attribute type if it doesn't already exist and will return the integer ID for the type. 

\section bb_set Posting to the Blackboard

To add an attribute to the #TSK_GEN_INFO artifact for a file, first create a TskBlackboardAttribute of the desired type using one of the TskBlackboardAttribute constructors, then call TskFile::addGenInfoAttribute() on the TskFile object that represents the file.  

To post other types of attributes, you'll need to either create a new artifact for the file or add the attribute to an existing artifact. 
To support the former, the TskFile and TskBlackboard interfaces define overloaded TskFile::createArtifact() / TskBlackboard::createArtifact() factory functions that return TskBlackboardArtifact objects, and the TskBlackboardArtifact class provides a TskBlackboardArtifact::addAttribute() member function.
To support the latter, the TskFile and TskBlackboard interfaces includes overloaded TskFile::getArtifacts() / TskBlackboard::getArtifacts() functions that return a collection of TskBlackboardArtifact objects. 
Iterate through the collection to find the desired artifact, then construct a TskBlackboardAttribute object and call TskBlackboardArtifact::addAttribute().

\subsection bb_attr_context Attribute Context?

The context field is intended to be used sparingly, and the framework itself does not do anything with attribute context strings other than make them available for inspection. 

Consider, for example, a module that analyzes a Microsoft Word file, including determining when the document was last saved and when it was last printed. 
Both of these dates could be posted to the blackboard for use by a later module that makes activity timelines.  
One approach would be to make the dates TSK_DATETIME attributes of the #TSK_GEN_INFO artifact for the file, distinguishing the two attributes using "Last Printed" and "Last Saved" context values.
On the other hand, a more robust approach would be to create new "LastPrinted" and "LastSaved" attribute types and post corresponding attributes to the #TSK_GEN_INFO artifact. 
The latter approach would make it easier for the timeline module to retrieve the relevant attributes.    


\subsection bb_artifact2 Multiple Artifacts Versus Multiple Attributes?

In some cases, it may not be clear if you should post multiple single-attribute artifacts for a file or post a single multiple-attribute artifact.  
Here are some guidelines:

 - Attributes that are essentially self-contained data items such as #TSK_DATETIME_CREATED and #TSK_DATETIME_MODIFIED should be added to a file's #TSK_GEN_INFO artifact. 
 - If a single file is associated with multiple items of the same type (e.g., log entries in a log file, bookmarks in a bookmark file, cookies in a cookie database), then each instance should be posted as a separate artifact so that you can differentiate them and keep all related attributes clearly grouped (e.g., it is clear which date goes with which log entry).  
 - All attributes in artifacts other than #TSK_GEN_INFO artifacts should be closely related to each other.  


 \section bb_query  Querying the Blackboard

 The TskFile interface defines a set of member functions that provide a convenient way to obtain the artifacts and attributes associated with the file a TskFile instance represents.
 
 The TskBlackboard interface provides similar functions that take a file ID as one of their arguments, as well as more general purpose querying functions.
 
 
\section bb_artifacts_and_attributes Artifact and Attributes Examples

Please refer to (http://wiki.sleuthkit.org/index.php?title=Artifact_Examples).


*/
