Documentation of the libtocc

Introduction

libtocc is the engine of the Tocc project. All of the functionalities are implemented in this library. Other components are just UIs for libtocc. So, there can be different UIs that work in parallel.

libtocc have a very simple, clean and complete API. It is written in C++ but there can be wrappers for other languages.

This document explains how to use this library.

Quick Start

Compiling from Source

See How to Compile And Use libtocc for complete instruction of how to compile the libtocc. Usually, you can simply invoke these commands in order:

$ ./configure
$ make
$ make install

Note that latest command may need super user privilage.

A Minimal Example

The following is a minimal example of an application that uses libtocc:

 1#include <iostream>
 2#include "libtocc.h"
 3
 4int main(int argc, char* argv[])
 5{
 6  // The argument is the path to where tocc-managed files should be
 7  // kept. Replace it with an existing path.
 8  libtocc::Manager manager("/opt/tocc-managed/");
 9
10  // Initializing the base-path.
11  // Note that it should be done once for each path. You will receive an
12  // exception if you call this method for an already-initialized path.
13  manager.initialize();
14
15  // Importing a file from the file system to the tocc-managed file system.
16  // The second argument is the title of this file.
17  libtocc::FileInfo new_file_info =
18    manager.import_file("/home/aidin/photos/portrate01.jpeg",
19                        "A Beautiful Portrate");
20
21 // Printing out information of the copied file.
22 std::cout << new_file_info << std::endl;
23}

Put it in sample.cpp file, and then simply compile it:

$g++ -o sample sample.cpp -ltocc -lunqlite

Note: You also have to link your application against the libunqlite.so. Because libtocc depends on it.

Here’s an explanation of what happened. First, you need to include libtocc.h which defines libtocc::Manager, the interface of the libtocc. All of the Tocc functionalities are accessible through Manager class. In its constructor, it gets a path to a directory that it should keeps its files and database. After that, we invoked the libtocc::Manager::initialize() method. It will initialized the path we passed to the Manager constructor. Now, we can import files using libtocc::Manager::import_file() method. It will copy a file from the traditional file system to the tocc-managed file system. It’s a photo, and its title is “A Beautiful Portrate”.

Where to go from here