Difference between revisions of "Truxton C API"

From truxwiki.com
Jump to navigation Jump to search
Line 55: Line 55:
  
 
==Functions==
 
==Functions==
 
 
* [[truxton_create]] - Creates a Truxton object
 
* [[truxton_create]] - Creates a Truxton object
 
* [[truxton_destroy]] - Frees a Truxton object
 
* [[truxton_destroy]] - Frees a Truxton object
Line 64: Line 63:
 
* [[truxton_route_message]] - Send a message to down-stream ETL processors
 
* [[truxton_route_message]] - Send a message to down-stream ETL processors
  
==ETL Application Creation==
+
==Artifacts==
* [[truxton_etl_create]] - Creates a Truxton ETL object
+
Artifacts are pieces of information that are also known as entities.
* [[truxton_etl_destroy]] - Destroys a Truxton ETL object
+
 
* [[truxton_etl_add_command_line_argument]] - Adds a command line argument
+
* [[truxton_artifact_create]] - Creates a new artifact object
* [[truxton_etl_add_desired_file_type]] - Tells Truxton what types of files you want to process
+
* [[truxton_artifact_destroy]] - Destroys an existing artifact object
* [[truxton_etl_get_description]] - Retrieves the human readable description of this exploitation process
+
* [[truxton_artifact_save]] - Saves the artifact to the <code><nowiki>[</nowiki>[[Entity Table|Entity]]<nowiki>]</nowiki></code> table in the database
* [[truxton_etl_set_description]] - Sets a description that has meaning to another human about this exploitation process
+
* [[truxton_artifact_get_data_type]] - Retrieves the raw data type
* [[truxton_etl_get_message]] - Halts the execution of your program until a message arrives from your message queue
+
* [[truxton_artifact_set_data_type]] - Sets the raw data type
* [[truxton_etl_get_stage_number]] - Retreives the [[ETL Stages | stage ]] of this exploitation process
+
* [[truxton_artifact_get_file_id]] - Retrieves the identifier of the file the artifact was found in
* [[truxton_etl_set_stage_number]] - Sets the [[ETL Stages | stage]] at which this exploitation process should run
+
* [[truxton_artifact_set_file_id]] - Sets the identifier of the file the artifact was found in
* [[truxton_etl_set_application_name]] - Sets the name of your application
+
* [[truxton_artifact_get_id]] - After saving, retrieves the identifier of the artifact
* [[truxton_etl_set_depot_type]] - Sets the type of depot you want to use
+
* [[truxton_artifact_get_length]] - Retrieves the number of bytes in the raw data that make up this artifact
* [[truxton_etl_set_depot_type_name]] - Sets a seed name for the type of depot you want to use
+
* [[truxton_artifact_set_length]] - Sets the number of bytes in the raw data that make up this artifact
* [[truxton_etl_set_expander_identifier]] - Sets an identifier to use during reprocessing
+
* [[truxton_artifact_get_media_id]] - Retrieves the identifier of the media this artifact is in
* [[truxton_etl_set_expander_version]] - Sets a custom version of your process
+
* [[truxton_artifact_set_media_id]] - Sets the identifier of the media this artifact is in
* [[truxton_etl_set_queue_name]] - Sets the name of the message queue for this process
+
* [[truxton_artifact_get_object_id]] - Retrieves the identifier of the object the artifact came from
* [[truxton_etl_set_thread_safe]] - Tells Truxton if it is safe to use your message handler in a multi-threaded fashion
+
* [[truxton_artifact_set_object_id]] - Sets the identifier of the object the artifact came from
* [[truxton_etl_set_poly_file_expander]] - Tells Truxton you are a file expander that needs multiple source files
+
* [[truxton_artifact_get_object_type]] - Retrieves the type of object the artifact came from
* [[truxton_etl_send_me_file_id]] - Used during development and debugging
+
* [[truxton_artifact_set_object_type]] - Sets the type of object the artifact came from
* [[truxton_etl_send_me_files]] - Used during development and debugging
+
* [[truxton_artifact_get_offset]] - Retrieves the offset in the file where the artifact came from
* [[truxton_etl_send_me_hash]] - Used during development and debugging
+
* [[truxton_artifact_set_offset]] - Sets the offset in the file where the artifact came from
* [[truxton_etl_send_me_local_file]] - Used during development and debugging
+
* [[truxton_artifact_get_value]] - Retrieves the value of the artifact
 +
* [[truxton_artifact_set_value]] - Sets the value of the artifact
  
 
==Child Files==
 
==Child Files==
Line 142: Line 142:
 
* [[truxton_child_file_new_child]] - Creates a child of this file
 
* [[truxton_child_file_new_child]] - Creates a child of this file
  
==File IO==
+
==ETL Application Creation==
* [[truxton_file_open_id]] - Retrieves a particular file specified by the file's [https://en.wikipedia.org/wiki/Universally_unique_identifier GUID].
+
* [[truxton_etl_create]] - Creates a Truxton ETL object
* [[truxton_file_open_md5]] - Retrieves the first file in Truxton whose contents have the given [https://en.wikipedia.org/wiki/MD5 MD5] hash.
+
* [[truxton_etl_destroy]] - Destroys a Truxton ETL object
* [[truxton_file_close]] - Closes the contents. You will no longer be able to read from the file.
+
* [[truxton_etl_add_command_line_argument]] - Adds a command line argument
* [[truxton_file_free]] - Deallocates any resources allocated for this object. The file is no longer valid after this call.
+
* [[truxton_etl_add_desired_file_type]] - Tells Truxton what types of files you want to process
* [[truxton_file_tell]] - Returns the current file pointer position.
+
* [[truxton_etl_get_description]] - Retrieves the human readable description of this exploitation process
* [[truxton_file_length]] - Returns the number of bytes in the file's contents.
+
* [[truxton_etl_set_description]] - Sets a description that has meaning to another human about this exploitation process
* [[truxton_file_is_closed]] - Tells you if the file has been closed or not.
+
* [[truxton_etl_get_message]] - Halts the execution of your program until a message arrives from your message queue
* [[truxton_file_seek]] - Changes the file pointer.
+
* [[truxton_etl_get_stage_number]] - Retreives the [[ETL Stages | stage ]] of this exploitation process
* [[truxton_file_readline]] - Reads a single line of text from the file.
+
* [[truxton_etl_set_stage_number]] - Sets the [[ETL Stages | stage]] at which this exploitation process should run
* [[truxton_file_read]] - Reads bytes from the file.
+
* [[truxton_etl_set_application_name]] - Sets the name of your application
 
+
* [[truxton_etl_set_depot_type]] - Sets the type of depot you want to use
==File Record Fields==
+
* [[truxton_etl_set_depot_type_name]] - Sets a seed name for the type of depot you want to use
* [[truxton_file_get_accessed]] - Reads the file's last access timestamp in [https://docs.microsoft.com/en-us/windows/win32/api/minwinbase/ns-minwinbase-filetime FILETIME] ticks
+
* [[truxton_etl_set_expander_identifier]] - Sets an identifier to use during reprocessing
* [[truxton_file_get_attributes]] - Reads the attributes of the file
+
* [[truxton_etl_set_expander_version]] - Sets a custom version of your process
* [[truxton_file_get_content_status]] - Reads the [[Content Status | status]] of the file's contents
+
* [[truxton_etl_set_queue_name]] - Sets the name of the message queue for this process
* [[truxton_file_get_created]] - Reads the file's creation timestamp in [https://docs.microsoft.com/en-us/windows/win32/api/minwinbase/ns-minwinbase-filetime FILETIME] ticks
+
* [[truxton_etl_set_thread_safe]] - Tells Truxton if it is safe to use your message handler in a multi-threaded fashion
* [[truxton_file_get_depot_id]] - Reads the [https://en.wikipedia.org/wiki/Universally_unique_identifier GUID] of the [[Depot | depot]] holding the file's contents
+
* [[truxton_etl_set_poly_file_expander]] - Tells Truxton you are a file expander that needs multiple source files
* [[truxton_file_get_depot_length]] - Reads the number of bytes in the [[Depot | depot]] taken by this file's contents
+
* [[truxton_etl_send_me_file_id]] - Used during development and debugging
* [[truxton_file_get_depot_name]] - Reads the file name of the [[Depot | depot]] holding this file's contents
+
* [[truxton_etl_send_me_files]] - Used during development and debugging
* [[truxton_file_get_depot_offset]] - The offset from the beginning of the [[Depot | depot]] where this file's contents begin
+
* [[truxton_etl_send_me_hash]] - Used during development and debugging
* [[truxton_file_get_disk_offset]] - Reads physical offset of the first byte of the file's contents
+
* [[truxton_etl_send_me_local_file]] - Used during development and debugging
* [[truxton_file_get_entropy]] - Reads the [https://en.wikipedia.org/wiki/Entropy_(information_theory) entropy] of the file's contents
 
* [[truxton_file_get_hash]] - Reads the [https://en.wikipedia.org/wiki/MD5 MD5] of the file's contents
 
* [[truxton_file_get_id]] - Reads the file's [https://en.wikipedia.org/wiki/Universally_unique_identifier GUID]
 
* [[truxton_file_get_is_eliminated]] - Tells you of the file's contents were discarded
 
* [[truxton_file_get_is_resident]] - Tells you if the file's contents exist contiguously within its parent
 
* [[truxton_file_get_media_id]] - Reads the [https://en.wikipedia.org/wiki/Universally_unique_identifier GUID] of the file's media
 
* [[truxton_file_get_modified]] - Reads the file's last write timestamp in [https://docs.microsoft.com/en-us/windows/win32/api/minwinbase/ns-minwinbase-filetime FILETIME] ticks
 
* [[truxton_file_get_number_of_children]] - Returns the number of files that have this one as their parent
 
* [[truxton_file_get_name]] - Reads the name of the file
 
* [[truxton_file_get_number_of_children]] - Returns the number of files that have this one as their parent
 
* [[truxton_file_get_origin]] - Reads the [[Origin | origin]] of the file's contents
 
* [[truxton_file_get_parent_id]] - Reads the [https://en.wikipedia.org/wiki/Universally_unique_identifier GUID] of the file's parent
 
* [[truxton_file_get_size]] - Reads the size of the file as recorded in the directory entry for the file
 
* [[truxton_file_get_signature]] - Gets the first four bytes of the contents as an integer
 
* [[truxton_file_get_type]] - Reads the [[File Types Supported|type]] of the file
 
 
 
==File Actions==
 
These are things your can do to a file.
 
These are not data items stored in the database.
 
* [[truxton_file_change_type]] - Allows you to change the [[File Types Supported | type]] of the file
 
* [[truxton_file_get_details]] - Retrieves JSON with details of the file's contents
 
* [[truxton_file_get_truxton]] - Retrieves the Truxton connection used to get this file
 
  
==Create Objects from File==
+
===Debugging===
The following APIs are used to create objects with a file as their parent.
 
* [[truxton_file_create_artifact]] - Creates and associates an artifact with this file. The artifact be saved to the <code><nowiki>[</nowiki>[[Entity Table|Entity]]<nowiki>]</nowiki></code> table.
 
* [[truxton_file_create_child]] - For creating a file.
 
* [[truxton_file_create_event]] - Creates and associates an event with this file. The event will be saved to the <code><nowiki>[</nowiki>[[Event Table|Event]]<nowiki>]</nowiki></code> table.
 
* [[truxton_file_create_exif]] - Creates and associates camera information with this file. The data will be saved to the <code><nowiki>[</nowiki>[[EXIF Table|EXIF]]<nowiki>]</nowiki></code> table.
 
* [[truxton_file_create_location]] - Creates and associates a geographic location with this file. The data will be saved to the <code><nowiki>[</nowiki>[[Location Table|Location]]<nowiki>]</nowiki></code> table.
 
* [[truxton_file_create_relation]] - Creates a relationship with this file as the source. The data will be saved to the <code><nowiki>[</nowiki>[[Relation Table|Relation]]<nowiki>]</nowiki></code> table.
 
* [[truxton_file_create_url]] - Creates a website visit with this file as the source. This data will be saved to the <code><nowiki>[</nowiki>[[WebsiteVisit Table|WebsiteVisit]]<nowiki>]</nowiki></code> table.
 
* [[truxton_file_create_usb]] - Creates a USB device with this file as the source. This data will be saved to the <code><nowiki>[</nowiki>[[USBDevice Table|USBDevice]]<nowiki>]</nowiki></code> table.
 
* [[truxton_file_tag]] - Creates a tag and puts it on this file. This data will be saved to the <code>[Tagged]</code> table.
 
 
 
==Debugging==
 
 
* [[truxton_etl_send_me_file_id]] - Puts a message in your queue given a [https://en.wikipedia.org/wiki/Universally_unique_identifier GUID] that matches the <code>[ID]</code> column of the <code><nowiki>[</nowiki>[[File Table|File]]<nowiki>]</nowiki></code> table.
 
* [[truxton_etl_send_me_file_id]] - Puts a message in your queue given a [https://en.wikipedia.org/wiki/Universally_unique_identifier GUID] that matches the <code>[ID]</code> column of the <code><nowiki>[</nowiki>[[File Table|File]]<nowiki>]</nowiki></code> table.
 
* [[truxton_etl_send_me_files]] - Put a specified number messages in your queue of a particular [[File Types Supported|file type.]]  
 
* [[truxton_etl_send_me_files]] - Put a specified number messages in your queue of a particular [[File Types Supported|file type.]]  
 
* [[truxton_etl_send_me_hash]] - Put one file that matches an [https://en.wikipedia.org/wiki/MD5 MD5] hash.
 
* [[truxton_etl_send_me_hash]] - Put one file that matches an [https://en.wikipedia.org/wiki/MD5 MD5] hash.
 
* [[truxton_etl_send_me_local_file]] - Put a specified file on your system into your message queue.
 
* [[truxton_etl_send_me_local_file]] - Put a specified file on your system into your message queue.
 
==Media==
 
These are the API's that allow you to add to the Media table in the database.
 
* [[truxton_media_create]] - Creates a new media object
 
* [[truxton_media_open_id]] - Opens an existing media in the database given the media's [https://en.wikipedia.org/wiki/Universally_unique_identifier GUID].
 
* [[truxton_media_destroy]] - Frees any resources allocated to this object
 
* [[truxton_media_get_id]] - Retrieves the [https://en.wikipedia.org/wiki/Universally_unique_identifier GUID] of the media
 
* [[truxton_media_set_id]] - Sets the [https://en.wikipedia.org/wiki/Universally_unique_identifier GUID] of the media
 
* [[truxton_media_get_name]] - Retrieves the name of the media
 
* [[truxton_media_set_name]] - Sets the name of the media
 
* [[truxton_media_get_description]] - Retrieves the longer description of the media
 
* [[truxton_media_set_description]] - Sets the description of the media
 
* [[truxton_media_get_case_number]] - Retrieves the case identifier of the media
 
* [[truxton_media_set_case_number]] - Sets the case identifier of the media
 
* [[truxton_media_get_originator]] - Retrieves who asked you to process the media
 
* [[truxton_media_set_originator]] - Sets the origin of the media
 
* [[truxton_media_get_evidence_bag]] - Retrieves the identifier of the evidence bag the media is being kept in
 
* [[truxton_media_set_evidence_bag]] - Records the identifier of the evidence bag the media is stored in.
 
* [[truxton_media_get_status]] - Retrieves the [[Media Status|status]] of the media
 
* [[truxton_media_set_status]] - Sets the [[Media Status|status]] of the media
 
* [[truxton_media_get_type]] - Retrieves the [[Media Types|type]] of the media
 
* [[truxton_media_set_type]] - Sets the [[Media Types|type]] of the media
 
* [[truxton_media_get_created]] - Retrieves when the media was created
 
* [[truxton_media_set_created]] - Sets when the media was created
 
* [[truxton_media_get_last_updated]] - Retrieves when the media was last updated
 
* [[truxton_media_set_last_updated]] - Sets when the media was last updated
 
* [[truxton_media_get_expires]] - Retrieves the expiration date of the media
 
* [[truxton_media_set_expires]] - Sets the expiration date of the media
 
* [[truxton_media_get_percent_complete]] - Retrieves the completeness the processing of this media
 
* [[truxton_media_set_percent_complete]] - Sets the completeness the processing of this media
 
* [[truxton_media_get_load_configuration_id]] - Retrieves the load configuration of this media
 
* [[truxton_media_set_load_configuration_id]] - Sets the load configuration of this media
 
* [[truxton_media_get_size]] - Retrieves the size, in bytes, of the original media
 
* [[truxton_media_set_size]] - Sets the size, in bytes, of the original media
 
* [[truxton_media_get_latitude]] - Retrieves the [https://en.wikipedia.org/wiki/Latitude latitude] portion of the [https://en.wikipedia.org/wiki/World_Geodetic_System#WGS84 WGS84] coordinates of where the media was seized.
 
* [[truxton_media_set_latitude]] - Sets the [https://en.wikipedia.org/wiki/Latitude latitude] portion of the [https://en.wikipedia.org/wiki/World_Geodetic_System#WGS84 WGS84] coordinates of where the media was seized.
 
* [[truxton_media_get_longitude]] - Retrieves the [https://en.wikipedia.org/wiki/Longitude longitude] portion of the [https://en.wikipedia.org/wiki/World_Geodetic_System#WGS84 WGS84] coordinates of where the media was seized.
 
* [[truxton_media_set_longitude]] - Sets the [https://en.wikipedia.org/wiki/Longitude longitude] portion of the [https://en.wikipedia.org/wiki/World_Geodetic_System#WGS84 WGS84] coordinates of where the media was seized.
 
* [[truxton_media_get_generated_files_folder_id]] - Retrieves the [https://en.wikipedia.org/wiki/Universally_unique_identifier GUID] of the Generated Files folder in the media
 
* [[truxton_media_get_root_file_id]] - Retrieves the [https://en.wikipedia.org/wiki/Universally_unique_identifier GUID] of the top level file in the media
 
* [[truxton_media_add_child]] - Created a child file object belonging to this media.
 
* [[truxton_media_save]] - Saves the media information to the database
 
* [[truxton_media_tag]] - Associating a tag with this media
 
 
==Message==
 
This is the message sent on the message bus between the ETL processes.
 
 
* [[truxton_message_create]] - Creates a new message object
 
* [[truxton_message_destroy]] - Destroys the message object
 
* [[truxton_message_get_queue_is_empty]] - Tells you if the message queue is empty
 
* [[truxton_message_set_queue_is_empty]] - Sets the empty-queue attribute
 
* [[truxton_message_get_route_id]] - Retrieves the route this message is taking
 
* [[truxton_message_set_route_id]] - Sets the route the message should take
 
* [[truxton_message_get_priority]] - Retrieves the priority of the message
 
* [[truxton_message_set_priority]] - Sets the priority of the message
 
* [[truxton_message_get_file_id]] - Retrieves the identifier of the file
 
* [[truxton_message_set_file_id]] - Sets the identifier of the file
 
* [[truxton_message_get_parent_id]] - Retrieves the parent file identifier
 
* [[truxton_message_set_parent_id]] - Sets the parent file identifier
 
* [[truxton_message_get_media_id]] - Retrieves the media identifier
 
* [[truxton_message_set_media_id]] - Sets the media identifier
 
* [[truxton_message_get_depot_id]] - Retrieves the depot identifier
 
* [[truxton_message_set_depot_id]] - Sets the depot identifier
 
* [[truxton_message_get_depot_offset]] - Retrieves the offset into the depot of the first byte of the file's contents
 
* [[truxton_message_set_depot_offset]] - Sets the offset into the depot of the first byte of the file's contents
 
* [[truxton_message_get_depot_length]] - Retrieves the number of bytes in the depot for this file's contents
 
* [[truxton_message_set_depot_length]] - Sets the number of bytes in the depot for this file's contents
 
* [[truxton_message_get_hash]] - Retrieves the [https://en.wikipedia.org/wiki/MD5 MD5] hash (digital fingerprint) of the file's contents
 
* [[truxton_message_set_hash]] - Sets the [https://en.wikipedia.org/wiki/MD5 MD5] hash (digital fingerprint) of the file's contents
 
* [[truxton_message_get_signature]] - Retrieves the first four bytes of the contents as an integer
 
* [[truxton_message_set_signature]] - Sets the first four bytes of the contents as an integer
 
* [[truxton_message_get_file_type]] - Retrieves the [[File Types Supported|type]] of the file
 
* [[truxton_message_set_file_type]] - Sets the [[File Types Supported|type]] of the file
 
* [[truxton_message_get_depot_name]] - Retrieves the name of the file that stores this file's contents
 
* [[truxton_message_set_depot_name]] - Sets the name of the file that stores this file's contents
 
* [[truxton_message_get_dont_route]] - Retrieves the Don't Route flag
 
* [[truxton_message_set_dont_route]] - Sets the Don't Route flag
 
* [[truxton_message_get_truxton]] - Retrieves the Truxton handle
 
* [[truxton_message_set_truxton]] - Sets the Truxton handle
 
 
==File Export==
 
* [[truxton_file_export_create]] - Creates a new file export object
 
* [[truxton_file_export_destroy]] - Destroys an existing file export object
 
* [[truxton_file_export_execute]] - Exports files
 
* [[truxton_file_export_add_criteria]] - Adds a criteria to the export
 
* [[truxton_file_export_set_option]] - Sets options for the export
 
* [[truxton_file_export_where_clause]] - Retrieves the [https://en.wikipedia.org/wiki/SQL SQL] <code>WHERE</code> clause of the current criteria
 
 
==Artifacts==
 
Artifacts are pieces of information that are also known as entities.
 
 
* [[truxton_artifact_create]] - Creates a new artifact object
 
* [[truxton_artifact_destroy]] - Destroys an existing artifact object
 
* [[truxton_artifact_save]] - Saves the artifact to the <code><nowiki>[</nowiki>[[Entity Table|Entity]]<nowiki>]</nowiki></code> table in the database
 
* [[truxton_artifact_get_data_type]] - Retrieves the raw data type
 
* [[truxton_artifact_set_data_type]] - Sets the raw data type
 
* [[truxton_artifact_get_file_id]] - Retrieves the identifier of the file the artifact was found in
 
* [[truxton_artifact_set_file_id]] - Sets the identifier of the file the artifact was found in
 
* [[truxton_artifact_get_id]] - After saving, retrieves the identifier of the artifact
 
* [[truxton_artifact_get_length]] - Retrieves the number of bytes in the raw data that make up this artifact
 
* [[truxton_artifact_set_length]] - Sets the number of bytes in the raw data that make up this artifact
 
* [[truxton_artifact_get_media_id]] - Retrieves the identifier of the media this artifact is in
 
* [[truxton_artifact_set_media_id]] - Sets the identifier of the media this artifact is in
 
* [[truxton_artifact_get_object_id]] - Retrieves the identifier of the object the artifact came from
 
* [[truxton_artifact_set_object_id]] - Sets the identifier of the object the artifact came from
 
* [[truxton_artifact_get_object_type]] - Retrieves the type of object the artifact came from
 
* [[truxton_artifact_set_object_type]] - Sets the type of object the artifact came from
 
* [[truxton_artifact_get_offset]] - Retrieves the offset in the file where the artifact came from
 
* [[truxton_artifact_set_offset]] - Sets the offset in the file where the artifact came from
 
* [[truxton_artifact_get_value]] - Retrieves the value of the artifact
 
* [[truxton_artifact_set_value]] - Sets the value of the artifact
 
  
 
==Event==
 
==Event==
 
If you need to save a significant place in time, use the following functions.
 
If you need to save a significant place in time, use the following functions.
 
These will create a record in the <code><nowiki>[</nowiki>[[Event Table|Event]]<nowiki>]</nowiki></code> table.
 
These will create a record in the <code><nowiki>[</nowiki>[[Event Table|Event]]<nowiki>]</nowiki></code> table.
 
 
* [[truxton_event_create]] - Creates a new event object
 
* [[truxton_event_create]] - Creates a new event object
 
* [[truxton_event_destroy]] - Destroys an existing event object
 
* [[truxton_event_destroy]] - Destroys an existing event object
Line 404: Line 258:
 
* [[truxton_exif_get_lens_serial_number_offset]]
 
* [[truxton_exif_get_lens_serial_number_offset]]
 
* [[truxton_exif_set_lens_serial_number_offset]]
 
* [[truxton_exif_set_lens_serial_number_offset]]
 +
 +
==File==
 +
===File Actions===
 +
These are things your can do to a file.
 +
These are not data items stored in the database.
 +
* [[truxton_file_change_type]] - Allows you to change the [[File Types Supported | type]] of the file
 +
* [[truxton_file_get_details]] - Retrieves JSON with details of the file's contents
 +
* [[truxton_file_get_truxton]] - Retrieves the Truxton connection used to get this file
 +
 +
===File IO===
 +
* [[truxton_file_open_id]] - Retrieves a particular file specified by the file's [https://en.wikipedia.org/wiki/Universally_unique_identifier GUID].
 +
* [[truxton_file_open_md5]] - Retrieves the first file in Truxton whose contents have the given [https://en.wikipedia.org/wiki/MD5 MD5] hash.
 +
* [[truxton_file_close]] - Closes the contents. You will no longer be able to read from the file.
 +
* [[truxton_file_free]] - Deallocates any resources allocated for this object. The file is no longer valid after this call.
 +
* [[truxton_file_tell]] - Returns the current file pointer position.
 +
* [[truxton_file_length]] - Returns the number of bytes in the file's contents.
 +
* [[truxton_file_is_closed]] - Tells you if the file has been closed or not.
 +
* [[truxton_file_seek]] - Changes the file pointer.
 +
* [[truxton_file_readline]] - Reads a single line of text from the file.
 +
* [[truxton_file_read]] - Reads bytes from the file.
 +
 +
===File Record Fields===
 +
* [[truxton_file_get_accessed]] - Reads the file's last access timestamp in [https://docs.microsoft.com/en-us/windows/win32/api/minwinbase/ns-minwinbase-filetime FILETIME] ticks
 +
* [[truxton_file_get_attributes]] - Reads the attributes of the file
 +
* [[truxton_file_get_content_status]] - Reads the [[Content Status | status]] of the file's contents
 +
* [[truxton_file_get_created]] - Reads the file's creation timestamp in [https://docs.microsoft.com/en-us/windows/win32/api/minwinbase/ns-minwinbase-filetime FILETIME] ticks
 +
* [[truxton_file_get_depot_id]] - Reads the [https://en.wikipedia.org/wiki/Universally_unique_identifier GUID] of the [[Depot | depot]] holding the file's contents
 +
* [[truxton_file_get_depot_length]] - Reads the number of bytes in the [[Depot | depot]] taken by this file's contents
 +
* [[truxton_file_get_depot_name]] - Reads the file name of the [[Depot | depot]] holding this file's contents
 +
* [[truxton_file_get_depot_offset]] - The offset from the beginning of the [[Depot | depot]] where this file's contents begin
 +
* [[truxton_file_get_disk_offset]] - Reads physical offset of the first byte of the file's contents
 +
* [[truxton_file_get_entropy]] - Reads the [https://en.wikipedia.org/wiki/Entropy_(information_theory) entropy] of the file's contents
 +
* [[truxton_file_get_hash]] - Reads the [https://en.wikipedia.org/wiki/MD5 MD5] of the file's contents
 +
* [[truxton_file_get_id]] - Reads the file's [https://en.wikipedia.org/wiki/Universally_unique_identifier GUID]
 +
* [[truxton_file_get_is_eliminated]] - Tells you of the file's contents were discarded
 +
* [[truxton_file_get_is_resident]] - Tells you if the file's contents exist contiguously within its parent
 +
* [[truxton_file_get_media_id]] - Reads the [https://en.wikipedia.org/wiki/Universally_unique_identifier GUID] of the file's media
 +
* [[truxton_file_get_modified]] - Reads the file's last write timestamp in [https://docs.microsoft.com/en-us/windows/win32/api/minwinbase/ns-minwinbase-filetime FILETIME] ticks
 +
* [[truxton_file_get_number_of_children]] - Returns the number of files that have this one as their parent
 +
* [[truxton_file_get_name]] - Reads the name of the file
 +
* [[truxton_file_get_number_of_children]] - Returns the number of files that have this one as their parent
 +
* [[truxton_file_get_origin]] - Reads the [[Origin | origin]] of the file's contents
 +
* [[truxton_file_get_parent_id]] - Reads the [https://en.wikipedia.org/wiki/Universally_unique_identifier GUID] of the file's parent
 +
* [[truxton_file_get_size]] - Reads the size of the file as recorded in the directory entry for the file
 +
* [[truxton_file_get_signature]] - Gets the first four bytes of the contents as an integer
 +
* [[truxton_file_get_type]] - Reads the [[File Types Supported|type]] of the file
 +
 +
===Derived Objects===
 +
The following APIs are used to create objects with a file as their parent.
 +
* [[truxton_file_create_artifact]] - Creates and associates an artifact with this file. The artifact be saved to the <code><nowiki>[</nowiki>[[Entity Table|Entity]]<nowiki>]</nowiki></code> table.
 +
* [[truxton_file_create_child]] - For creating a file.
 +
* [[truxton_file_create_event]] - Creates and associates an event with this file. The event will be saved to the <code><nowiki>[</nowiki>[[Event Table|Event]]<nowiki>]</nowiki></code> table.
 +
* [[truxton_file_create_exif]] - Creates and associates camera information with this file. The data will be saved to the <code><nowiki>[</nowiki>[[EXIF Table|EXIF]]<nowiki>]</nowiki></code> table.
 +
* [[truxton_file_create_location]] - Creates and associates a geographic location with this file. The data will be saved to the <code><nowiki>[</nowiki>[[Location Table|Location]]<nowiki>]</nowiki></code> table.
 +
* [[truxton_file_create_relation]] - Creates a relationship with this file as the source. The data will be saved to the <code><nowiki>[</nowiki>[[Relation Table|Relation]]<nowiki>]</nowiki></code> table.
 +
* [[truxton_file_create_url]] - Creates a website visit with this file as the source. This data will be saved to the <code><nowiki>[</nowiki>[[WebsiteVisit Table|WebsiteVisit]]<nowiki>]</nowiki></code> table.
 +
* [[truxton_file_create_usb]] - Creates a USB device with this file as the source. This data will be saved to the <code><nowiki>[</nowiki>[[USBDevice Table|USBDevice]]<nowiki>]</nowiki></code> table.
 +
* [[truxton_file_tag]] - Creates a tag and puts it on this file. This data will be saved to the <code>[Tagged]</code> table.
 +
 +
==File Export==
 +
* [[truxton_file_export_create]] - Creates a new file export object
 +
* [[truxton_file_export_destroy]] - Destroys an existing file export object
 +
* [[truxton_file_export_execute]] - Exports files
 +
* [[truxton_file_export_add_criteria]] - Adds a criteria to the export
 +
* [[truxton_file_export_set_option]] - Sets options for the export
 +
* [[truxton_file_export_where_clause]] - Retrieves the [https://en.wikipedia.org/wiki/SQL SQL] <code>WHERE</code> clause of the current criteria
  
 
==File Type==
 
==File Type==
Line 443: Line 363:
 
* [[truxton_location_get_when]]
 
* [[truxton_location_get_when]]
 
* [[truxton_location_set_when]]
 
* [[truxton_location_set_when]]
 +
 +
==Media==
 +
These are the API's that allow you to add to the Media table in the database.
 +
* [[truxton_media_create]] - Creates a new media object
 +
* [[truxton_media_open_id]] - Opens an existing media in the database given the media's [https://en.wikipedia.org/wiki/Universally_unique_identifier GUID].
 +
* [[truxton_media_destroy]] - Frees any resources allocated to this object
 +
* [[truxton_media_get_id]] - Retrieves the [https://en.wikipedia.org/wiki/Universally_unique_identifier GUID] of the media
 +
* [[truxton_media_set_id]] - Sets the [https://en.wikipedia.org/wiki/Universally_unique_identifier GUID] of the media
 +
* [[truxton_media_get_name]] - Retrieves the name of the media
 +
* [[truxton_media_set_name]] - Sets the name of the media
 +
* [[truxton_media_get_description]] - Retrieves the longer description of the media
 +
* [[truxton_media_set_description]] - Sets the description of the media
 +
* [[truxton_media_get_case_number]] - Retrieves the case identifier of the media
 +
* [[truxton_media_set_case_number]] - Sets the case identifier of the media
 +
* [[truxton_media_get_originator]] - Retrieves who asked you to process the media
 +
* [[truxton_media_set_originator]] - Sets the origin of the media
 +
* [[truxton_media_get_evidence_bag]] - Retrieves the identifier of the evidence bag the media is being kept in
 +
* [[truxton_media_set_evidence_bag]] - Records the identifier of the evidence bag the media is stored in.
 +
* [[truxton_media_get_status]] - Retrieves the [[Media Status|status]] of the media
 +
* [[truxton_media_set_status]] - Sets the [[Media Status|status]] of the media
 +
* [[truxton_media_get_type]] - Retrieves the [[Media Types|type]] of the media
 +
* [[truxton_media_set_type]] - Sets the [[Media Types|type]] of the media
 +
* [[truxton_media_get_created]] - Retrieves when the media was created
 +
* [[truxton_media_set_created]] - Sets when the media was created
 +
* [[truxton_media_get_last_updated]] - Retrieves when the media was last updated
 +
* [[truxton_media_set_last_updated]] - Sets when the media was last updated
 +
* [[truxton_media_get_expires]] - Retrieves the expiration date of the media
 +
* [[truxton_media_set_expires]] - Sets the expiration date of the media
 +
* [[truxton_media_get_percent_complete]] - Retrieves the completeness the processing of this media
 +
* [[truxton_media_set_percent_complete]] - Sets the completeness the processing of this media
 +
* [[truxton_media_get_load_configuration_id]] - Retrieves the load configuration of this media
 +
* [[truxton_media_set_load_configuration_id]] - Sets the load configuration of this media
 +
* [[truxton_media_get_size]] - Retrieves the size, in bytes, of the original media
 +
* [[truxton_media_set_size]] - Sets the size, in bytes, of the original media
 +
* [[truxton_media_get_latitude]] - Retrieves the [https://en.wikipedia.org/wiki/Latitude latitude] portion of the [https://en.wikipedia.org/wiki/World_Geodetic_System#WGS84 WGS84] coordinates of where the media was seized.
 +
* [[truxton_media_set_latitude]] - Sets the [https://en.wikipedia.org/wiki/Latitude latitude] portion of the [https://en.wikipedia.org/wiki/World_Geodetic_System#WGS84 WGS84] coordinates of where the media was seized.
 +
* [[truxton_media_get_longitude]] - Retrieves the [https://en.wikipedia.org/wiki/Longitude longitude] portion of the [https://en.wikipedia.org/wiki/World_Geodetic_System#WGS84 WGS84] coordinates of where the media was seized.
 +
* [[truxton_media_set_longitude]] - Sets the [https://en.wikipedia.org/wiki/Longitude longitude] portion of the [https://en.wikipedia.org/wiki/World_Geodetic_System#WGS84 WGS84] coordinates of where the media was seized.
 +
* [[truxton_media_get_generated_files_folder_id]] - Retrieves the [https://en.wikipedia.org/wiki/Universally_unique_identifier GUID] of the Generated Files folder in the media
 +
* [[truxton_media_get_root_file_id]] - Retrieves the [https://en.wikipedia.org/wiki/Universally_unique_identifier GUID] of the top level file in the media
 +
* [[truxton_media_add_child]] - Created a child file object belonging to this media.
 +
* [[truxton_media_save]] - Saves the media information to the database
 +
* [[truxton_media_tag]] - Associating a tag with this media
 +
 +
==Message==
 +
This is the message sent on the message bus between the ETL processes.
 +
* [[truxton_message_create]] - Creates a new message object
 +
* [[truxton_message_destroy]] - Destroys the message object
 +
* [[truxton_message_get_queue_is_empty]] - Tells you if the message queue is empty
 +
* [[truxton_message_set_queue_is_empty]] - Sets the empty-queue attribute
 +
* [[truxton_message_get_route_id]] - Retrieves the route this message is taking
 +
* [[truxton_message_set_route_id]] - Sets the route the message should take
 +
* [[truxton_message_get_priority]] - Retrieves the priority of the message
 +
* [[truxton_message_set_priority]] - Sets the priority of the message
 +
* [[truxton_message_get_file_id]] - Retrieves the identifier of the file
 +
* [[truxton_message_set_file_id]] - Sets the identifier of the file
 +
* [[truxton_message_get_parent_id]] - Retrieves the parent file identifier
 +
* [[truxton_message_set_parent_id]] - Sets the parent file identifier
 +
* [[truxton_message_get_media_id]] - Retrieves the media identifier
 +
* [[truxton_message_set_media_id]] - Sets the media identifier
 +
* [[truxton_message_get_depot_id]] - Retrieves the depot identifier
 +
* [[truxton_message_set_depot_id]] - Sets the depot identifier
 +
* [[truxton_message_get_depot_offset]] - Retrieves the offset into the depot of the first byte of the file's contents
 +
* [[truxton_message_set_depot_offset]] - Sets the offset into the depot of the first byte of the file's contents
 +
* [[truxton_message_get_depot_length]] - Retrieves the number of bytes in the depot for this file's contents
 +
* [[truxton_message_set_depot_length]] - Sets the number of bytes in the depot for this file's contents
 +
* [[truxton_message_get_hash]] - Retrieves the [https://en.wikipedia.org/wiki/MD5 MD5] hash (digital fingerprint) of the file's contents
 +
* [[truxton_message_set_hash]] - Sets the [https://en.wikipedia.org/wiki/MD5 MD5] hash (digital fingerprint) of the file's contents
 +
* [[truxton_message_get_signature]] - Retrieves the first four bytes of the contents as an integer
 +
* [[truxton_message_set_signature]] - Sets the first four bytes of the contents as an integer
 +
* [[truxton_message_get_file_type]] - Retrieves the [[File Types Supported|type]] of the file
 +
* [[truxton_message_set_file_type]] - Sets the [[File Types Supported|type]] of the file
 +
* [[truxton_message_get_depot_name]] - Retrieves the name of the file that stores this file's contents
 +
* [[truxton_message_set_depot_name]] - Sets the name of the file that stores this file's contents
 +
* [[truxton_message_get_dont_route]] - Retrieves the Don't Route flag
 +
* [[truxton_message_set_dont_route]] - Sets the Don't Route flag
 +
* [[truxton_message_get_truxton]] - Retrieves the Truxton handle
 +
* [[truxton_message_set_truxton]] - Sets the Truxton handle
  
 
==Options==
 
==Options==
Line 473: Line 471:
 
* [[truxton_relation_set_relation]]
 
* [[truxton_relation_set_relation]]
  
==Website Visit==
+
==URL==
 
* [[truxton_url_create]]
 
* [[truxton_url_create]]
 
* [[truxton_url_destroy]]
 
* [[truxton_url_destroy]]

Revision as of 09:53, 2 December 2020

Truxton functionality is exposed to the C programming world as a DLL named TruxtonCAPI.dll in the C:\Program Files\Truxton\SDK folder. This DLL can be called from any programming language that has the ability to make operating system calls.

Philosophy

The API is considered to be "flat" in that only sixty-four bit integers and ASCII character strings are used in the interface. This was chosen to make it easy for other languages to call the API. The coding convention is all lower case names with underscores separating words. Truxton is a member of the east const posse.

Creating a lib

Truxton doesn't ship a linker library for TruxtonCAPI.dll in order not to tie the developer to any particular compiler. If you want to link TruxtonCAPI.dll with your own C/C++ code, you will need to generate a linker library.

Generating a Linker Library for Microsoft Compilers

You can download a free Visual Studio from Microsoft. The steps to produce a LIB file from a DLL are:

  1. Generate a module definition (DEF) file from TruxtonCAPI.dll.
  2. Use the DEF file to create the linker library (LIB) file.

Generate a Module Definition File

The following Powershell script will create the DEF file.

$dumpbin = "C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Tools\MSVC\14.28.29333\bin\Hostx64\x64\dumpbin.exe"

$lines = (& $dumpbin /exports TruxtonCAPI.dll)

Write-Output "EXPORTS"

foreach ( $line in $lines )
{
   if ( $line.Contains(" = ") -EQ $true )
   {
      Write-Output $line.SubString($line.IndexOf(" = ") + 3)
   }
}

In your SDK folder, execute the script from Powershell:

MakeDef.ps1 >TruxtonCAPI.def

Generate a LIB File

Now that you have the DEF file, you can create the linker library using lib.exe (which is found in the same folder as dumpbin.exe) in the command window:

lib.exe /def:TruxtonCAPI.def /out:TruxtonCAPI.lib /machine:x64

API Groups

The API is broken down into the different areas of Truxton.

Initialization

Functions

Artifacts

Artifacts are pieces of information that are also known as entities.

Child Files

A child file is one that you have created and need to save in Truxton.

Creating things related to this file:

ETL Application Creation

Debugging

Event

If you need to save a significant place in time, use the following functions. These will create a record in the [Event] table.

EXIF (Camera Information)

File

File Actions

These are things your can do to a file. These are not data items stored in the database.

File IO

File Record Fields

Derived Objects

The following APIs are used to create objects with a file as their parent.

File Export

File Type

Geographic Location

Media

These are the API's that allow you to add to the Media table in the database.

Message

This is the message sent on the message bus between the ETL processes.

Options

Truxton "options" are otherwise known as configuration settings, command line options, etc. They are configuration items that your program can use.

Relation

URL

USB Device