Class Creator

Class Documentation

class Creator

The Creator is responsible to create a zim file.

Once the Creator is instantiated, it can be configured with the config* methods. Then the creation process must be started with startZimCreation. Elements of the zim file can be added using the add* methods. The final steps is to call finishZimCreation.

During the creation of the zim file (and before the call to finishZimCreation), some values must be set using the set* methods.

All add* methods and finishZimCreation can throw a exception. (most of the time zim::CreatorError child but not limited to) It is up to the user to catch this exception and handle the error. The current (documented) conditions when a exception is thrown are:

  • When a entry cannot be added (mainly because a entry with the same path has already been added) A zim::InvalidEntry will be thrown. The creator will still be in a valid state and the creation can continue.

  • An exception has been thrown in a worker thread. This exception will be catch and rethrown through a zim::AsyncError. The creator will be set in a invalid state and creation cannot continue.

  • The creator is in error state. A zim::CreatorStateError will be thrown.

  • Any exception thrown by user implementation itself. Note that this exception may be thrown in a worker thread and so being “catch” by a AsyncError.

  • Any other exception thrown for unknown reason. By default, creator status is not changed by thrown exception and creation should stop.

Public Functions

Creator()

Creator constructor.

Parameters:

  • verbose – If the creator print verbose information.

  • comptype – The compression algorithm to use.

virtual ~Creator()
Creator &configVerbose(bool verbose)

Configure the verbosity of the creator

Parameters:

verbose – if the creator print verbose information.

Returns:

a reference to itself.

Creator &configCompression(Compression compression)

Configure the compression algorithm to use.

Parameters:

comptype – the compression algorithm to use.

Returns:

a reference to itself.

Creator &configClusterSize(zim::size_type targetSize)

Set the size of the created clusters.

The creator will try to create cluster with (uncompressed) size as close as possible to targetSize without exceeding that limit. If not possible, the only such case being an item larger than targetSize, a separated cluster will be allocated for that oversized item.

Be carefull with this value. Bigger value means more content put together, so a better compression ratio. But it means also that more decompression has to be made when reading a blob. If you don’t know which value to put, don’t use this method and let libzim use the default value.

Parameters:

targetSize – The target size of a cluster (in byte).

Returns:

a reference to itself.

Creator &configIndexing(bool indexing, const std::string &language)

Configure the fulltext indexing feature.

Parameters:

  • indexing – True if we must fulltext index the content.

  • language – Language to use for the indexation.

Returns:

a reference to itself.

Creator &configNbWorkers(unsigned nbWorkers)

Set the number of thread to use for the internal worker.

Parameters:

nbWorkers – The number of workers to use.

Returns:

a reference to itself.

void startZimCreation(const std::string &filepath)

Start the zim creation.

The creator must have been configured before calling this method.

Parameters:

filepath – the path of the zim file to create.

void addItem(std::shared_ptr<Item> item)

Add a item to the archive.

Parameters:

item – The item to add.

void addMetadata(const std::string &name, const std::string &content, const std::string &mimetype = "text/plain;charset=utf-8")

Add a metadata to the archive.

Parameters:

  • name – the name of the metadata

  • content – the content of the metadata

  • mimetype – the mimetype of the metadata. Only used to detect if the metadata must be compressed or not.

void addMetadata(const std::string &name, std::unique_ptr<ContentProvider> provider, const std::string &mimetype = "text/plain;charset=utf-8")

Add a metadata to the archive using a contentProvider instead of plain string.

Parameters:

  • name – the name of the metadata.

  • provider – the provider of the content of the metadata.

  • mimetype – the mimetype of the metadata. Only used to detect if the metadata must be compressed.

void addIllustration(unsigned int size, const std::string &content)

Add illustration to the archive.

Parameters:

  • size – the size (width and height) of the illustration.

  • content – the content of the illustration (must be a png content)

void addIllustration(unsigned int size, std::unique_ptr<ContentProvider> provider)

Add illustration to the archive.

Parameters:

  • size – the size (width and height) of the illustration.

  • provider – the provider of the content of the illustration (must be a png content)

void addRedirection(const std::string &path, const std::string &title, const std::string &targetpath, const Hints &hints = Hints())

Add a redirection to the archive.

Hints (especially FRONT_ARTICLE) can be used to put the redirection in the front articles list. By default, redirections are not front article.

Parameters:

  • path – the path of the redirection.

  • title – the title of the redirection.

  • targetpath – the path of the target of the redirection.

  • hints – hints associated to the redirection.

void addAlias(const std::string &path, const std::string &title, const std::string &targetPath, const Hints &hints = Hints())

Add a alias of a existing entry.

The existing entry pointed by targetPath is cloned and updated with path and title.

The alias entry will shared the same type (redirection or item) and namespace than targetPath.

If the targetPath is a item, the new entry will be item pointing to the same data than targetPath item. (Not a redirection to targetPath). However, the alias entry is not counted in the media type counter and it is not fulltext indexed (only title indexed).

Hints can be given to influence creator handling (front article, …) as it is done for redirection.

Parameters:

  • path – the path of the alias

  • title – the title of the alias

  • targetPath – the path of the aliased entry.

  • hints – hints associated to the alias.

void finishZimCreation()

Finalize the zim creation.

inline void setMainPath(const std::string &mainPath)

Set the path of the main page.

Parameters:

mainPath – The path of the main page.

inline void setUuid(const zim::Uuid &uuid)

Set the uuid of the the archive.

Parameters:

uuid – The uuid of the archive.