Difference between revisions of "Truxton C API"

From truxwiki.com
Jump to navigation Jump to search
Line 347: Line 347:
  
 
==Geographic Location==
 
==Geographic Location==
* [[truxton_location_create]]
+
* [[truxton_location_create]] - Creates geographic location. The data will be saved to the <code><nowiki>[</nowiki>[[Location Table|Location]]<nowiki>]</nowiki></code> table
* [[truxton_location_destroy]]
+
* [[truxton_location_destroy]] - Destroys the location object.
* [[truxton_location_save]]
+
* [[truxton_location_save]] - Saves the information in the object to the <code><nowiki>[</nowiki>[[Location Table|Location]]<nowiki>]</nowiki></code> table
* [[truxton_location_get_id]]
+
* [[truxton_location_get_id]] - After saving, retrieves the [https://en.wikipedia.org/wiki/Universally_unique_identifier GUID] of the event
* [[truxton_location_get_file_id]]
+
* [[truxton_location_get_file_id]] - Retrieves the [https://en.wikipedia.org/wiki/Universally_unique_identifier GUID] of the file the location came from
* [[truxton_location_set_file_id]]
+
* [[truxton_location_set_file_id]] - Sets the [https://en.wikipedia.org/wiki/Universally_unique_identifier GUID] of the file this location came from
* [[truxton_location_get_media_id]]
+
* [[truxton_location_get_media_id]] - Retrieves the [https://en.wikipedia.org/wiki/Universally_unique_identifier GUID] of the media this location came from
* [[truxton_location_set_media_id]]
+
* [[truxton_location_set_media_id]] - Sets the [https://en.wikipedia.org/wiki/Universally_unique_identifier GUID] of the media this location came from
* [[truxton_location_get_altitude]]
+
* [[truxton_location_get_altitude]] - Retrieves the altitude, in meters, of this location
* [[truxton_location_set_altitude]]
+
* [[truxton_location_set_altitude]] - Sets the altitude, in meters, of this location
* [[truxton_location_get_label]]
+
* [[truxton_location_get_label]] - Retrieves the short title of this location
* [[truxton_location_set_label]]
+
* [[truxton_location_set_label]] - Sets the short description of this location
* [[truxton_location_get_latitude]]
+
* [[truxton_location_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 this location
* [[truxton_location_set_latitude]]
+
* [[truxton_location_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 this location
* [[truxton_location_get_longitude]]
+
* [[truxton_location_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 this location
* [[truxton_location_set_longitude]]
+
* [[truxton_location_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 this location
* [[truxton_location_get_type]]
+
* [[truxton_location_get_type]] - Retrieves the [Location Types|type] of the location
* [[truxton_location_set_type]]
+
* [[truxton_location_set_type]] - Sets the [Location Types|type] of the location
* [[truxton_location_get_when]]
+
* [[truxton_location_get_when]] - Retrieves the date and time associated with this location
* [[truxton_location_set_when]]
+
* [[truxton_location_set_when]] - Sets the date and time associated with this location
  
 
==Media==
 
==Media==

Revision as of 12:05, 11 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.

Preparing for Use

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

Alternatively, you can use a plugin pattern of calling LoadLibrary then many calls to GetProcAddress to get the function pointers. This is a lot of work and very prone to errors.

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.

Derived Objects

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.

Derived Objects

The following APIs are used to create objects with an event as their parent.

  • truxton_event_tag - Creates a tag and puts it on this event. This data will be saved to the [Tagged] 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.

Derived Objects

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

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