Libzim

From openZIM
Jump to navigation Jump to search

ZIMlib is the library which implements the access to ZIM files. Use libzim in your own software - like reader applications - to make them ZIM-capable without the need having to dig too much into the ZIM file format.

Programming

zimlib is written in C++. To use the library, you need the include files of zimlib have to link against libzim. Both are installed when zimlib is built with the normal "./configure; make; make install".

Errors are handled with exceptions. When something goes wrong, zimlib throws an error, which is always derived from std::exception.

All Classes are defined in the namespace zim. Copying is allowed and tried to make as cheap as possible. The library is not thread safe by itself. You have to serialize access to the class yourself.

The main class, which accesses the file is zim::File. It has actually a reference to a implementation, so that copies of the class just references the same file. You open a file by passing the file name to the constuctor as a std::string.

The API tries to resemble the standard C++ library, so that a zim::File works like a container of instances of zim::Article. It has a const_iterator, which is created using zim::File::begin(). The iterator may be incremented to point to the next article until it reaches zim::File::end(). Iterators pointing to that must not be dereferenced nor incremented.

When the iterator is created using zim::File::beginByTitle(), the articles are ordered by title. Otherwise the url field is used.

Sample
List all articles titles inside a ZIM file
#include <zim/file.h>
#include <zim/fileiterator.h>
#include <iostream>

int main(int argc, char* argv[]) 
{
  try
  {
    zim::File f("wikipedia.zim");
  
    for (zim::File::const_iterator it = f.begin(); it != f.end(); ++it)
    {
      std::cout << "url: " << it->getUrl() << " title: " << it->getTitle() << '
';
    }
  }
  catch (const std::exception& e)
  {
    std::cerr << e.what() << std::endl;
  }
}

Methods

Article File::getArticle(char ns, const QUnicodeString& title, bool collate = false)

returns an object of an article

std::string Article::getPage(bool layout = true, unsigned maxRecurse = 10)

returns the content of an article