Reference of libtocc API

Header files of libtocc are structured in directories. But for the ease of use, there’s a single header file called libtocc.h, which included all the other header files.

Thus, You only need to include libtocc.h in your code.

Just for you curiosity, this document told you which class is defined in which header file.

libtocc::Manager

Available in libtocc/front_end/manager.h

libtocc::Manager(const char* base_path)

To work with libtocc, you need to create an instance of this class.

base_path is the absolute path to where Tocc should keep its files. (the tocc-managed file system.) Note that it have to be absolute.

Note: Instances of libtocc::Manager are NOT thread-safe. In other words, you shouldn’t share instances of it between threads. If you want to work multi-threaded, each of the threads should instanciate their own libtocc::Manager.

void libtocc::Manager::initialize()

Initializes the base_path (the path provided in constructor).

This will create the database in the base_path, and creates the required collections inside of it. This should be called once for each base_path, or else you can’t work with it.

Note that this shouldn’t be called more than once for the same base_path. You will receive an exception if you do so.

Note: Your application shouldn’t automatically initialize every path it receive from the user. User may enter a wrong path by mistake, and your application silently initialize that path and, for example, imports user’s files somewhere they didn’t really want to. And their files will be lost. Instead, tell your users to run tocc-initialize on the path manually, or provide a function to let them do it manually from your application.

libtocc::FileInfo libtocc::Manager::get_file_info(const char *file_id)

Returns information of a specific file. file_id is the ID of the file you want its information. It throw exception if no file with this ID found.

libtocc::FileInfo libtocc::Manager::import_file(const char *source_path, const char *title = "", const char *traditional_path = "")

Copies a file from another file system to tocc-managed file system.

This is the basic way to add a file to tocc-managed file system.

source_path is the absolute path to where the file exists in the traditional file system. title is what this file calls, and traditional_path is a special property that can be set to handle compatibility with traditional file systems.

Since no tag is passed, a default tag will be assign to the new file.

It returns the information of the newly copied file.

libtocc::FileInfo libtocc::Manager::import_file(const char *source_path, const char *title = "", const char *traditional_path = "", const TagsCollection *tags)

Another overload of import_file. Same as the previous function, but it also accepts tags. These tags will be assign to the copied file.

void libtocc::Manager::remove_file(const char *file_id)

Deletes the specified file, both from the database and file system.

file_id is the ID of the file to be removed. ID of files can be gained by libtocc::FileInfo::get_id() method.

void libtocc::Manager::remove_file(FileInfo &file_to_remote)

Overload of the previous function, which accepts a libtocc::FileInfo instead of the file ID.

void libtocc::Manager::remove_files(const char *file_ids[], int file_ids_size)

Deletes a list of files from the file system and the database.

file_ids is an array of files IDs to be removed. file_ids_size is the size of that array.

void libtocc::Manager::remove_files(FileInfoCollection &files_to_remove)

Overload of the previous function, which accepts an instance of libtocc::FileInfoCollection instead of an array of IDs.

void libtocc::Manager::assign_tags(const char *file_ids[], int file_ids_size, const TagsCollection *tags)

Assigns a list of tags to a list of files. All of the tags will be assign to each file.

file_ids is an array of IDs of files to assign tags to. file_id_size is the size of the file_ids array. If you pass zero or a negative number as file_id_size, the method itself will calculate the size. If you have the size in your hand, it’s better to pass it. tags is the list of tags to assign to these files.

void libtocc::Manager::assign_tags(const char *file_id, const TagsCollection *tags)

Overload of the previous function that accepts a file and a list of tags.

void libtocc::Manager::assign_tags(const char *file_id, const char *tag)

Overload of the previous function that accepts a single file and a single tag.

void libtocc::Manager::unassign_tag(const char *file_id, const char *tag)

Unassign a tag from the specified file.

file_id is the file to unassign the tag from it. tag is the tag to unassign.

void libtocc::Manager::unassign_tags(const char *file_ids[], int file_ids_size, const TagsCollection *tags)

Overload of the previous method, which accepts a list of files and a list of tags. It unassign all of the specified tags from all of the specified files.

file_id_size is the size of the file_ids array. If you pass zero or a negative number as file_id_size, the method itself will calculate the size. If you have the size in your hand, it’s better to pass it.

void libtocc::Manager::unassign_tags(const char *file_id, const TagsCollection *tags)

Overloads of the previous method, which accepts an instance of libtocc::TagsCollection instead of an array of tags.

FileInfoCollection libtocc::Manager::search_files(Query &query)

Executes the specified query, and returns all of the files that matches with it.

It returns an empty collection if nothing found.

See also libtocc::Query.

TagStatisticsCollection libtocc::Manager::get_tags_statistics()

Returns a list of tags that are available in database, and number of files each tag assigned to.

TagStatisticsCollection libtocc::Manager::get_tags_statistics(const char *file_ids[], int file_ids_size)

Overload of the previous method, which only returns statistics of the specified files. It means, it returns all the tags that are assigned to these files, and number of files assigned to these tags.

file_ids is an array of file IDs to get their statistics. file_ids_size is the size of that array.

void libtocc::Manager::set_titles(const char *file_ids[], int file_ids_size, const char *new_title)

Sets the specified title for all of the files in the specified list.

void libtocc::Manager::set_title(const char *file_id, const char *new_title)

Sets the specified title to the specified file.

FileInfo Class

Available in libtocc/front_end/file_info.h

class FileInfo

This class keeps information about a file.

Normally, you don’t need to create an instance of this class. This is the return type of some of the API methods.

const char *libtocc::FileInfo::get_id() const

Returns ID of the file.

TagsCollection libtocc::FileInfo::get_tags() const

Returns a list of tags that are assigned to the file.

const char *libtocc::FileInfo::get_title() const

Returns title of the file.

const char *libtocc::FileInfo::get_traditional_path() const

Returns traditional path of the file.

const char *libtocc::FileInfo::get_physical_path() const

Returns physical path of the file (where file exists on the Tocc-managed file system).

std::ostream& operator<<

This operator will be put a formatted string (in a JSON-like format) of the class into the ostream. For example, it can be used to print out the file info:

libtocc::FileInfo copied_file = manager.import_file("/path/to/file");
std::cout << copied_file << std::endl;

which will print out something like:

{
  file_id: 0003a50
  title:
  traditional_path:
  tags: [uncategorized, ]
}

TagsCollection class

This class keeps a list of tags.

Available in libtocc/front_end/file_info.h

class libtocc::TagsCollection

Construct an empty collection.

libtocc::TagsCollection(const char* tags[], int size=-1)

Constructs a collection of tags with specified tags in it.

tags is the array of tags to initialize collection with. size is the size of the array. If you pass a zero or nagetive number as size, the method itself calculates the size. But if you have the size in hand, you better pass it.

libtocc::TagsCollection(int size)

Constructs a collection of tags. size will be reserve.

void libtocc::TagsCollection::add_tag(const char *tag)

Adds a tag to the collection.

void libtocc::TagsCollection::remove_tag(const char *tag)

Removes the specified tag from the collection.

bool libtocc::TagsCollection::contains(const char *tag)

Returns true if the tag exists in the collection.

int libtocc::TagsCollection::size() const

Returns number of elements in the collection.

bool libtocc::TagsCollection::is_empty() const

Returns true if the collection is empty.

TagsCollection::Iterator class

Available in libtocc/front_end/file_info.h

Iterator of the TagsCollection. Usage example:

TagsCollection tags;
// Adding some elements to `tags'.
tags.add("photo");
tags.add("abstract");

// Iteratoring over the collection.
TagsCollection::Iterator iterator(&tags);
for (; !iterator.is_finished(); ++iterator)
{
  // Printing out each element.
  std::cout << *iterator << std::endl;
}

libtocc::TagsCollection::Iterator(const libtocc::TagsCollection* collection)

Creates an iterator. collection is the collection to iterate over.

void libtocc::TagsCollection::Iterator::next()

Moves to the next element. (This also can be done using ++ operator.)

bool libtocc::TagsCollection::Iterator::is_finished()

Returns true if ends of the iteration reached.

const char *libtocc::TagsCollection::Iterator::get()

Gets the tag that iterator points to. It will be NULL if iterator passed end of the collection. (This method is equal to * operator.)

void libtocc::TagsCollection::Iterator::reset()

Resets the iterator. (Iterator will be points to the first element).