libkiwix

https://libkiwix.readthedocs.io/en/latest/
Admin
libkiwix is a C++ library providing common functionality and tools to manage ZIM files and power...
Tokens:59,270
Snippets:463
Trust Score:9.6
Update:5 days ago
Show doc for...
Tokens:
Raw
### Server::start()

Source: https://libkiwix.readthedocs.io/en/latest/api/classkiwix_1_1Server.html

Starts serving the content. Returns true if the server started successfully, false otherwise.

```APIDOC
## Server::start()

### Description
Starts serving the content.

### Returns
- **bool** - True if the server started successfully, false otherwise.

```

--------------------------------

### void KiwixServe::run()

Source: https://libkiwix.readthedocs.io/en/latest/api/classkiwix_1_1KiwixServe.html

Starts the server and begins serving requests. This method blocks until the server is shut down.

```APIDOC
## Method: run

### Description
Starts the server and begins serving requests. This method blocks until the server is shut down.

### Signature
```cpp
void run()
```

### Usage
```cpp
server.run();
```
```

--------------------------------

### Downloader::startDownload

Source: https://libkiwix.readthedocs.io/en/latest/api/program_listing_file_include_downloader.h.html

Starts a new download for the given URI and returns a shared pointer to the Download object.

```APIDOC
## Downloader::startDownload

### Description
Starts a new download for the given URI and returns a shared pointer to the Download object.

### Method
Member function

### Signature
`std::shared_ptr<Download> startDownload(const std::string& uri, const std::string& downloadDir, Options options = {})`

### Parameters
- **uri** (const std::string&) - Required - The URI of the file to download.
- **downloadDir** (const std::string&) - Required - The directory where the downloaded file will be saved.
- **options** (Options) - Optional - A vector of key-value pairs representing download options.

### Returns
A shared pointer to the Download object representing the started download.
```

--------------------------------

### Downloader::startDownload(const std::string &uri, const std::string &downloadDir, Options options = {})

Source: https://libkiwix.readthedocs.io/en/latest/api/classkiwix_1_1Downloader.html

Starts a new download. This method is thread safe and returns a pointer to a newly created Download or an existing one with a matching URI. If an existing download with the same URI is found, the options parameter is ignored.

```APIDOC
## Downloader::startDownload(const std::string &uri, const std::string &downloadDir, Options options = {})

### Description
Starts a new download. This method is thread safe and returns a pointer to a newly created Download or an existing one with a matching URI. If an existing download with the same URI is found, the options parameter is ignored.

### Method
startDownload

### Signature
`std::shared_ptr<Download> startDownload(const std::string &uri, const std::string &downloadDir, Options options = {})`

### Parameters
- **uri** (const std::string&) - Required - The URI of the thing to download.
- **downloadDir** (const std::string&) - Required - The download directory where the thing should be stored (takes precedence over any "dir" in `options`).
- **options** (Options) - Optional - A series of pair <option_name, option_value> to pass to aria.

### Returns
- **std::shared_ptr<Download>** - The newly created Download.

```

--------------------------------

### kiwix::getExecutablePath

Source: https://libkiwix.readthedocs.io/en/latest/api/ref_api.html

Gets the path of the current executable.

```APIDOC
## kiwix::getExecutablePath

### Description
Gets the path of the current executable.

### Function
`getExecutablePath()`

### Namespace
kiwix
```

--------------------------------

### kiwix::Downloader

Source: https://libkiwix.readthedocs.io/en/latest/api/ref_api.html

Manages multiple downloads. Provides methods to start, retrieve, and list downloads.

```APIDOC
## kiwix::Downloader

### Description
Manages multiple downloads. Provides methods to start, retrieve, and list downloads.

### Methods
- `Downloader()` - Constructor.
- `~Downloader()` - Destructor.
- `void close()` - Closes the downloader.
- `Download startDownload(const std::vector<std::string>& uris, const std::string& path)` - Starts a download for the given URIs and saves to the specified path.
- `Download getDownload(int did)` - Returns the download with the given ID.
- `int getNbDownload()` - Returns the number of active downloads.
- `std::vector<int> getDownloadIds()` - Returns the IDs of all downloads.

### Options
- `Options` - Configuration options for the downloader.
```

--------------------------------

### KiwixServe Class

Source: https://libkiwix.readthedocs.io/en/latest/_sources/api/program_listing_file_include_kiwixserve.h.rst.txt

The KiwixServe class provides an interface to start and manage a kiwix-serve subprocess. It allows setting the port, running the server, shutting it down, and checking if it is running.

```APIDOC
## KiwixServe Class

### Description
The KiwixServe class manages a subprocess that serves a library. It provides methods to run, shut down, and check the status of the server, as well as get and set the port.

### Constructor

#### KiwixServe(const std::string& libraryPath, int port = 8181)
- **libraryPath** (const std::string&) - Required - The path to the library file.
- **port** (int) - Optional - The port number to use. Defaults to 8181.

### Destructor

#### ~KiwixServe()
Destroys the KiwixServe object and cleans up resources.

### Methods

#### void run()
Starts the server subprocess.

#### void shutDown()
Stops the server subprocess.

#### bool isRunning()
Returns true if the server subprocess is running, false otherwise.

#### int getPort()
Returns the current port number.

#### int setPort(int port)
Sets the port number and returns the new port value.
- **port** (int) - Required - The new port number.

### Example
```cpp
#include <kiwixserve.h>

kiwix::KiwixServe server("/path/to/library.xml", 8080);
server.run();
if (server.isRunning()) {
    // server is running
}
server.shutDown();
```
```

--------------------------------

### Server::getServerAccessUrls() const

Source: https://libkiwix.readthedocs.io/en/latest/api/classkiwix_1_1Server.html

Gets the list of HTTP URLs through which the server can be contacted. Each URL is composed of an IP address and optional port and includes the root path component. In the current implementation at most 2 URLs may be returned - one for IPv4 and another for IPv6 protocol (whichever is available), as returned by getAddress(). Note, however, that the server may be also accessible via other IP-addresses/URLs (see setIpMode()).

```APIDOC
## Server::getServerAccessUrls() const

### Description
Gets the list of HTTP URLs through which the server can be contacted. Each URL is composed of an IP address and optional port and includes the root path component. In the current implementation at most 2 URLs may be returned - one for IPv4 and another for IPv6 protocol (whichever is available), as returned by getAddress(). Note, however, that the server may be also accessible via other IP-addresses/URLs (see setIpMode()).

### Returns
- **std::vector<std::string>** - List of HTTP URLs.

```

--------------------------------

### Server::setAddress(const std::string &addr)

Source: https://libkiwix.readthedocs.io/en/latest/api/classkiwix_1_1Server.html

Sets the IP address on which to listen for incoming connections. Specifying a non-empty IP address requires that the IpMode is set to IpMode::AUTO (which is the default). Otherwise, starting the server will fail.

```APIDOC
## Server::setAddress(const std::string &addr)

### Description
Sets the IP address on which to listen for incoming connections. Specifying a non-empty IP address requires that the IpMode is set to IpMode::AUTO (which is the default). Otherwise, starting the server will fail.

### Parameters
- **addr** (const std::string&) - Required - The IP address to listen on.

```

--------------------------------

### Downloader::getDownload(const std::string &did)

Source: https://libkiwix.readthedocs.io/en/latest/api/classkiwix_1_1Downloader.html

Gets a download corresponding to a download id (did). The user should call `update` on the returned Download to have an accurate status.

```APIDOC
## Downloader::getDownload(const std::string &did)

### Description
Gets a download corresponding to a download id (did). The user should call `update` on the returned Download to have an accurate status.

### Method
getDownload

### Signature
`std::shared_ptr<Download> getDownload(const std::string &did)`

### Parameters
- **did** (const std::string&) - Required - The download id to search for.

### Returns
- **std::shared_ptr<Download>** - The Download corresponding to did.

```

--------------------------------

### kiwix::getTranslatedString

Source: https://libkiwix.readthedocs.io/en/latest/api/ref_api.html

Gets a translated string.

```APIDOC
## kiwix::getTranslatedString

### Description
Gets a translated string.

### Function
`getTranslatedString()`

### Namespace
kiwix
```

--------------------------------

### kiwix::getSearchUrl

Source: https://libkiwix.readthedocs.io/en/latest/api/ref_api.html

Gets the search URL.

```APIDOC
## kiwix::getSearchUrl

### Description
Gets the search URL.

### Function
`getSearchUrl()`

### Namespace
kiwix
```

--------------------------------

### getBooksCategories

Source: https://libkiwix.readthedocs.io/en/latest/api/classkiwix_1_1Library.html

Gets all categories of the books in the library.

```APIDOC
## getBooksCategories

### Description
Gets all categories of the books in the library.

### Method
getBooksCategories

### Returns
- **std::vector<std::string>** - A list of categories.
```

--------------------------------

### getBooksLanguages

Source: https://libkiwix.readthedocs.io/en/latest/api/classkiwix_1_1Library.html

Gets all languages of the books in the library.

```APIDOC
## getBooksLanguages

### Description
Gets all languages of the books in the library.

### Method
getBooksLanguages

### Returns
- **std::vector<std::string>** - A list of languages.
```

--------------------------------

### create (static)

Source: https://libkiwix.readthedocs.io/en/latest/api/classkiwix_1_1Library.html

Creates a new Library instance.

```APIDOC
## create (static)

### Description
Creates a new Library instance.

### Method
create (static)

### Returns
- **LibraryPtr** - A pointer to the created Library instance.
```

--------------------------------

### kiwix::getLastPathElement

Source: https://libkiwix.readthedocs.io/en/latest/api/ref_api.html

Gets the last element of a path.

```APIDOC
## kiwix::getLastPathElement

### Description
Gets the last element of a path.

### Function
`getLastPathElement()`

### Namespace
kiwix
```

--------------------------------

### Full source code of kiwix.h header file

Source: https://libkiwix.readthedocs.io/en/latest/_sources/api/program_listing_file_include_kiwix.h.rst.txt

This is the complete listing of the include/kiwix.h file. It contains the GPL license header, the include guard KIWIX_H, and includes library.h. Use this as a reference for the file's structure and licensing.

```cpp
/*
 * Copyright 2011 Emmanuel Engelhart <kelson@kiwix.org>
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU  General Public License as published by
 * the Free Software Foundation; either version 3 of the License, or
 * any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
 * MA 02110-1301, USA.
 */

#ifndef KIWIX_H
#define KIWIX_H

#include "library.h"

#endif
```

--------------------------------

### void addBooksFromDirectory(const std::string &path, const bool verboseFlag = false)

Source: https://libkiwix.readthedocs.io/en/latest/api/classkiwix_1_1Manager.html

Adds all books from the directory tree into the library. Optionally enables verbose logging.

```APIDOC
## void addBooksFromDirectory(const std::string &path, const bool verboseFlag = false)

### Description
Adds all books from the directory tree into the library. Optionally enables verbose logging.

### Method
addBooksFromDirectory

### Parameters
- **path** (const std::string&) - Required - The path of the directory to scan.
- **verboseFlag** (const bool) - Optional - Verbose logs flag.
```

--------------------------------

### Bookmark()

Source: https://libkiwix.readthedocs.io/en/latest/api/classkiwix_1_1Bookmark.html

Creates an empty bookmark. The bookmark must be populated with set* methods.

```APIDOC
## Bookmark()

### Description
Creates an empty bookmark. The bookmark must be populated with set* methods.

### Method
Constructor

### Signature
`Bookmark()`

```

--------------------------------

### getBooksIds

Source: https://libkiwix.readthedocs.io/en/latest/api/classkiwix_1_1Library.html

Gets all book ids of the books in the library.

```APIDOC
## getBooksIds

### Description
Gets all book ids of the books in the library.

### Method
getBooksIds

### Returns
- **BookIdCollection** - A list of book ids.
```

--------------------------------

### Full header file include/bookmark.h

Source: https://libkiwix.readthedocs.io/en/latest/_sources/api/program_listing_file_include_bookmark.h.rst.txt

Complete source listing of the C++ header file bookmark.h. It declares the kiwix::Bookmark class with constructors, assignment operator, destructor, updateFromXml, getters, setters, and a private implementation pointer. The file is protected by include guards and includes <string> and "smartptr.h".

```cpp
/*
 * Copyright 2018 Matthieu Gautier <mgautier@kymeria.fr>
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU  General Public License as published by
 * the Free Software Foundation; either version 3 of the License, or
 * any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
 * MA 02110-1301, USA.
 */

#ifndef KIWIX_BOOKMARK_H
#define KIWIX_BOOKMARK_H

#include <string>
#include "smartptr.h"

namespace pugi {
class xml_node;
}

namespace kiwix
{

class Book;
class Bookmark
{
 public:
  Bookmark();

  Bookmark(const Book& book, const std::string& path, const std::string& title);

  Bookmark(const Bookmark& other);
  Bookmark& operator=(const Bookmark& other);

  ~Bookmark();

  void updateFromXml(const pugi::xml_node& node);

  std::string getBookId() const;
  std::string getBookTitle() const;
  std::string getBookName() const;
  std::string getBookFlavour() const;
  std::string getUrl() const;
  std::string getTitle() const;
  std::string getLanguage() const;
  std::string getDate() const;

  void setBookId(const std::string& bookId);
  void setBookTitle(const std::string& bookTitle);
  void setBookName(const std::string& bookName);
  void setBookFlavour(const std::string& bookFlavour);
  void setUrl(const std::string& url);
  void setTitle(const std::string& title);
  void setLanguage(const std::string& language);
  void setDate(const std::string& date);

 private:
  class Impl;
  ValuePtr<Impl> mp_impl;
};

}

#endif
```

--------------------------------

### getBookmarks

Source: https://libkiwix.readthedocs.io/en/latest/api/classkiwix_1_1Library.html

Gets all bookmarks, optionally only valid bookmarks.

```APIDOC
## getBookmarks

### Description
Gets all bookmarks, optionally only valid bookmarks.

### Method
getBookmarks

### Parameters
#### Parameters
- **onlyValidBookmarks** (bool) - Optional - If true, only return valid bookmarks. Default is true.

### Returns
- **const std::vector<kiwix::Bookmark>** - A list of bookmarks.
```

--------------------------------

### getBooksPublishers

Source: https://libkiwix.readthedocs.io/en/latest/api/classkiwix_1_1Library.html

Gets all book publishers of the books in the library.

```APIDOC
## getBooksPublishers

### Description
Gets all book publishers of the books in the library.

### Method
getBooksPublishers

### Returns
- **std::vector<std::string>** - A list of book publishers.
```

--------------------------------

### Bookmark(const Book &book, const std::string &path, const std::string &title)

Source: https://libkiwix.readthedocs.io/en/latest/api/classkiwix_1_1Bookmark.html

Creates a bookmark given a Book, a path, and a title.

```APIDOC
## Bookmark(const Book &book, const std::string &path, const std::string &title)

### Description
Creates a bookmark given a Book, a path, and a title.

### Method
Constructor

### Signature
`Bookmark(const Book &book, const std::string &path, const std::string &title)`

### Parameters
- **book** (const Book&) - Required - The book containing the article.
- **path** (const std::string&) - Required - The path to the article.
- **title** (const std::string&) - Required - The title of the bookmark.

```

--------------------------------

### Bookmark(const Bookmark &other)

Source: https://libkiwix.readthedocs.io/en/latest/api/classkiwix_1_1Bookmark.html

Copy constructor for Bookmark.

```APIDOC
## Bookmark(const Bookmark &other)

### Description
Copy constructor for Bookmark.

### Method
Constructor

### Signature
`Bookmark(const Bookmark &other)`

### Parameters
- **other** (const Bookmark&) - Required - The Bookmark object to copy.

```

--------------------------------

### getBooksCreators

Source: https://libkiwix.readthedocs.io/en/latest/api/classkiwix_1_1Library.html

Gets all book creators of the books in the library.

```APIDOC
## getBooksCreators

### Description
Gets all book creators of the books in the library.

### Method
getBooksCreators

### Returns
- **std::vector<std::string>** - A list of book creators.
```

--------------------------------

### Full source code of tools.h

Source: https://libkiwix.readthedocs.io/en/latest/_sources/api/program_listing_file_include_tools.h.rst.txt

This is the complete header file `include/tools.h` from the Libkiwix project. It declares utility functions and types in the `kiwix` namespace, including path manipulation, file operations, network interface queries, and language/category feed readers. The file is protected by include guards and includes the necessary standard headers.

```cpp
/*
 * Copyright 2021 Matthieu Gautier <mgautier@kymeria.fr>
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU  General Public License as published by
 * the Free Software Foundation; either version 3 of the License, or
 * any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
 * MA 02110-1301, USA.
 */

#ifndef KIWIX_TOOLS_H
#define KIWIX_TOOLS_H

#include <string>
#include <vector>
#include <map>
#include <cstdint>
#include "common.h"

namespace kiwix
{

struct IpAddress
{
    std::string addr;  
    std::string addr6; 
};

typedef std::pair<std::string, std::string> LangNameCodePair;
typedef std::vector<LangNameCodePair> FeedLanguages;
typedef std::vector<std::string> FeedCategories;

std::string getCurrentDirectory();

std::string getExecutablePath(bool realPathOnly = false);

bool isRelativePath(const std::string& path);

std::string appendToDirectory(const std::string& basePath, const std::string& relativePath);

std::string removeLastPathElement(const std::string& path);

std::string getLastPathElement(const std::string& path);

std::string computeAbsolutePath(const std::string& path, const std::string& relativePath);

std::string computeRelativePath(const std::string& path, const std::string& absolutePath);

void sleep(unsigned int milliseconds);

std::vector<std::string> split(const std::string& str, const std::string& delims, bool dropEmpty=true, bool keepDelim = false);

std::string converta2toa3(const std::string& a2code);

std::string getFileContent(const std::string& path);

bool fileExists(const std::string& path);

bool fileReadable(const std::string& path);

std::string getMimeTypeForFile(const std::string& filename);

std::map<std::string, IpAddress> getNetworkInterfacesIPv4Or6();

std::map<std::string, std::string> getNetworkInterfaces();

IpAddress getBestPublicIps();

std::string getBestPublicIp();

std::string beautifyFileSize(uint64_t number);

FeedLanguages readLanguagesFromFeed(const std::string& content);

FeedCategories readCategoriesFromFeed(const std::string& content);

std::string getLanguageSelfName(const std::string& lang);

std::string getSlugifiedFileName(const std::string& filename);

void setUserAgent(const std::string& userAgent);

std::string getUserAgent();
}
#endif // KIWIX_TOOLS_H
```

--------------------------------

### getBooksLanguagesWithCounts

Source: https://libkiwix.readthedocs.io/en/latest/api/classkiwix_1_1Library.html

Gets all languages of the books in the library with counts.

```APIDOC
## getBooksLanguagesWithCounts

### Description
Gets all languages of the books in the library with counts.

### Method
getBooksLanguagesWithCounts

### Returns
- **AttributeCounts** - A list of languages with the count of books in each language.
```

--------------------------------

### kiwixserve.h header file

Source: https://libkiwix.readthedocs.io/en/latest/_sources/api/program_listing_file_include_kiwixserve.h.rst.txt

This is the complete header file for the KiwixServe class. It declares a constructor that takes a library path and an optional port (default 8181), a destructor, and methods run(), shutDown(), isRunning(), getPort(), and setPort(). The class uses a unique_ptr to a Subprocess object.

```cpp
#ifndef KIWIXLIB_KIWIX_SERVE_H_
#define KIWIXLIB_KIWIX_SERVE_H_

#include <memory>
#include <string>

class Subprocess;
namespace kiwix {

class KiwixServe
{
  public:
    KiwixServe(const std::string& libraryPath, int port = 8181);
    ~KiwixServe();

    void run();
    void shutDown();
    bool isRunning();
    int getPort() { return m_port; }
    int setPort(int port);

  private:
  std::unique_ptr<Subprocess> mp_kiwixServe;
  int m_port;
  std::string m_libraryPath;
};

}; //end namespace kiwix

#endif // KIWIXLIB_KIWIX_SERVE_H_
```

--------------------------------

### Downloader::getDownloadIds() const

Source: https://libkiwix.readthedocs.io/en/latest/api/classkiwix_1_1Downloader.html

Gets the ids of the managed downloads.

```APIDOC
## Downloader::getDownloadIds() const

### Description
Gets the ids of the managed downloads.

### Method
getDownloadIds

### Signature
`std::vector<std::string> getDownloadIds() const`

### Returns
- **std::vector<std::string>** - The ids of the managed downloads.

```

--------------------------------

### Downloader::Downloader(std::string sessionFileDir)

Source: https://libkiwix.readthedocs.io/en/latest/api/classkiwix_1_1Downloader.html

Constructor for the Downloader class. Initializes a new Downloader instance with a session file directory.

```APIDOC
## Downloader::Downloader(std::string sessionFileDir)

### Description
Constructor for the Downloader class. Initializes a new Downloader instance with a session file directory.

### Method
Constructor

### Signature
`explicit Downloader(std::string sessionFileDir)`

### Parameters
- **sessionFileDir** (std::string) - Required - The directory for session files.

```

--------------------------------

### Server::getPort() const

Source: https://libkiwix.readthedocs.io/en/latest/api/classkiwix_1_1Server.html

Gets the port on which the server listens for incoming connections.

```APIDOC
## Server::getPort() const

### Description
Gets the port on which the server listens for incoming connections.

### Returns
- **int** - The port number.

```

--------------------------------

### Downloader::getNbDownload() const

Source: https://libkiwix.readthedocs.io/en/latest/api/classkiwix_1_1Downloader.html

Gets the number of downloads currently managed by the Downloader.

```APIDOC
## Downloader::getNbDownload() const

### Description
Gets the number of downloads currently managed by the Downloader.

### Method
getNbDownload

### Signature
`size_t getNbDownload() const`

### Returns
- **size_t** - The number of downloads currently managed.

```

--------------------------------

### Server::Server(std::shared_ptr<Library> library, std::shared_ptr<NameMapper> nameMapper = nullptr)

Source: https://libkiwix.readthedocs.io/en/latest/api/classkiwix_1_1Server.html

Constructs a Server instance with the given library and optional name mapper.

```APIDOC
## Server::Server(std::shared_ptr<Library> library, std::shared_ptr<NameMapper> nameMapper = nullptr)

### Description
Constructs a Server instance with the given library and optional name mapper.

### Parameters
- **library** (std::shared_ptr<Library>) - Required - The library to serve.
- **nameMapper** (std::shared_ptr<NameMapper>) - Optional - The name mapper to use (default nullptr).

```

--------------------------------

### Full source code of include/library.h

Source: https://libkiwix.readthedocs.io/en/latest/_sources/api/program_listing_file_include_library.h.rst.txt

This is the complete header file for the Libkiwix library. It defines the `kiwix::Filter` class for filtering books by various criteria, the `kiwix::ZimSearcher` class for search operations, and enums for sorting and filtering modes. The file also includes forward declarations and type aliases for library pointers.

```cpp
/*
 * Copyright 2011 Emmanuel Engelhart <kelson@kiwix.org>
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU  General Public License as published by
 * the Free Software Foundation; either version 3 of the License, or
 * any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
 * MA 02110-1301, USA.
 */

#ifndef KIWIX_LIBRARY_H
#define KIWIX_LIBRARY_H

#include <string>
#include <vector>
#include <map>
#include <memory>
#include <mutex>
#include <zim/archive.h>
#include <zim/search.h>

#include "book.h"
#include "bookmark.h"
#include "common.h"

#define KIWIX_LIBRARY_VERSION "20110515"

namespace Xapian {
class WritableDatabase;
};

namespace kiwix
{

class OPDSDumper;
class Library;

enum supportedListSortBy { UNSORTED, TITLE, SIZE, DATE, CREATOR, PUBLISHER };
enum supportedListMode {
  ALL = 0,
  LOCAL = 1,
  REMOTE = 1 << 1,
  NOLOCAL = 1 << 2,
  NOREMOTE = 1 << 3,
  VALID = 1 << 4,
  NOVALID = 1 << 5
};

enum MigrationMode {
  UPGRADE_ONLY = 0,

  ALLOW_DOWNGRADE = 1,
};

class Filter {
  public: // types
    using Tags = std::vector<std::string>;

  private: // data
    uint64_t activeFilters;
    Tags _acceptTags;
    Tags _rejectTags;
    std::string _category;
    std::string _lang;
    std::string _publisher;
    std::string _creator;
    size_t _maxSize;
    std::string _query;
    bool _queryIsPartial;
    std::string _name;
    std::string _flavour;

  public: // functions
    Filter();
    ~Filter() = default;

    Filter& local(bool accept);

    Filter& remote(bool accept);

    Filter& valid(bool accept);

    Filter& acceptTags(const Tags& tags);
    Filter& rejectTags(const Tags& tags);

    Filter& category(std::string category);

    Filter& lang(std::string lang);

    Filter& publisher(std::string publisher);
    Filter& creator(std::string creator);
    Filter& maxSize(size_t size);
    Filter& query(std::string query, bool partial=true);
    Filter& name(std::string name);
    Filter& flavour(std::string flavour);
    Filter& clearLang();
    Filter& clearCategory();

    bool hasQuery() const;
    const std::string& getQuery() const { return _query; }
    bool queryIsPartial() const { return _queryIsPartial; }

    bool hasName() const;
    const std::string& getName() const { return _name; }

    bool hasCategory() const;
    const std::string& getCategory() const { return _category; }

    bool hasLang() const;
    const std::string& getLang() const { return _lang; }

    bool hasPublisher() const;
    const std::string& getPublisher() const { return _publisher; }

    bool hasCreator() const;
    const std::string& getCreator() const { return _creator; }

    bool hasFlavour() const;
    const std::string& getFlavour() const { return _flavour; }

    const Tags& getAcceptTags() const { return _acceptTags; }
    const Tags& getRejectTags() const { return _rejectTags; }

private: // functions
    friend class Library;

    bool accept(const Book& book) const;
};


class ZimSearcher : public zim::Searcher
{
  public:
    explicit ZimSearcher(zim::Searcher&& searcher)
      : zim::Searcher(searcher)
    {}

    std::unique_lock<std::mutex> getLock() {
      return std::unique_lock<std::mutex>(m_mutex);
    }
    virtual ~ZimSearcher() = default;
  private:
    std::mutex m_mutex;
};

template<typename, typename>
class ConcurrentCache;

template<typename, typename>
class MultiKeyCache;

using LibraryPtr = std::shared_ptr<Library>;
using ConstLibraryPtr = std::shared_ptr<const Library>;


// Some compiler we use don't have [[nodiscard]] attribute.
// We don't want to declare `create` with it in this case.
#define LIBKIWIX_NODISCARD
#if defined __has_cpp_attribute
  #if __has_cpp_attribute (nodiscard)
```

--------------------------------

### getBookCount

Source: https://libkiwix.readthedocs.io/en/latest/api/classkiwix_1_1Library.html

Gets the number of books in the library, optionally counting local and remote books.

```APIDOC
## getBookCount

### Description
Gets the number of books in the library, optionally counting local and remote books.

### Method
getBookCount

### Parameters
#### Parameters
- **localBooks** (bool) - Required - If we must count local books (books with a path).
- **remoteBooks** (bool) - Required - If we must count remote books (books with an url).

### Returns
- **unsigned int** - The number of books.
```

--------------------------------

### void setUrl(const std::string &url)

Source: https://libkiwix.readthedocs.io/en/latest/api/classkiwix_1_1Bookmark.html

Sets the URL of the bookmark.

```APIDOC
## void setUrl(const std::string &url)

### Description
Sets the URL of the bookmark.

### Method
Setter

### Signature
`void setUrl(const std::string &url)`

### Parameters
- **url** (const std::string&) - Required - The URL to set.

```

--------------------------------

### Download::getFollowedBy

Source: https://libkiwix.readthedocs.io/en/latest/api/program_listing_file_include_downloader.h.html

Gets the ID of the 'second' download. Set only if the 'first' download is a metalink and is complete.

```APIDOC
## Download::getFollowedBy

### Description
Gets the ID of the 'second' download. Set only if the 'first' download is a metalink and is complete.

### Method
Member function

### Signature
`const std::string& getFollowedBy() const`

### Returns
The ID of the followed download as a string reference.
```

--------------------------------

### KiwixServe class declaration in kiwixserve.h

Source: https://libkiwix.readthedocs.io/en/latest/api/program_listing_file_include_kiwixserve.h.html

This header file defines the KiwixServe class, which manages a subprocess for serving a ZIM library. The constructor takes a library path and an optional port (default 8181). The class provides methods to run, shut down, check status, and get/set the port. It uses a unique_ptr to a Subprocess object and stores the port and library path as private members.

```cpp
#ifndef KIWIXLIB_KIWIX_SERVE_H_
#define KIWIXLIB_KIWIX_SERVE_H_

#include <memory>
#include <string>

class Subprocess;
namespace kiwix {

class KiwixServe
{
  public:
    KiwixServe(const std::string& libraryPath, int port = 8181);
    ~KiwixServe();

    void run();
    void shutDown();
    bool isRunning();
    int getPort() { return m_port; }
    int setPort(int port);

  private:
  std::unique_ptr<Subprocess> mp_kiwixServe;
  int m_port;
  std::string m_libraryPath;
};

}; //end namespace kiwix

#endif // KIWIXLIB_KIWIX_SERVE_H_

```

--------------------------------

### void setLanguage(const std::string &language)

Source: https://libkiwix.readthedocs.io/en/latest/api/classkiwix_1_1Bookmark.html

Sets the language of the bookmark.

```APIDOC
## void setLanguage(const std::string &language)

### Description
Sets the language of the bookmark.

### Method
Setter

### Signature
`void setLanguage(const std::string &language)`

### Parameters
- **language** (const std::string&) - Required - The language to set.

```

--------------------------------

### Manager::readBookmarkFile

Source: https://libkiwix.readthedocs.io/en/latest/api/classkiwix_1_1Manager.html

Loads a bookmark file.

```APIDOC
## readBookmarkFile

### Description
Loads a bookmark file.

### Parameters
- **path** (const std::string&) - Required - The path of the file to read.

### Returns
True if the content has been properly parsed.
```

--------------------------------

### version.h header file with version functions

Source: https://libkiwix.readthedocs.io/en/latest/_sources/api/program_listing_file_include_version.h.rst.txt

This is the complete content of the version.h header file. It defines the kiwix namespace, a LibVersions type as a vector of string pairs, and declares the functions getVersions() and printVersions(). The file is guarded by KIWIX_VERSION_H and includes standard headers.

```cpp
/*
 * Copyright 2021 Emmanuel Engelhart <kelson@kiwix.org>
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU  General Public License as published by
 * the Free Software Foundation; either version 3 of the License, or
 * any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
 * MA 02110-1301, USA.
 */

#ifndef KIWIX_VERSION_H
#define KIWIX_VERSION_H

#include <string>
#include <vector>
#include <iostream>

namespace kiwix
{
  typedef std::vector<std::pair<std::string, std::string>> LibVersions;
  LibVersions getVersions();
  void printVersions(std::ostream& out = std::cout);
}

#endif // KIWIX_VERSION_H
```

--------------------------------

### Class kiwix::i18n::GetTranslatedString

Source: https://libkiwix.readthedocs.io/en/latest/api/namespace_kiwix__i18n.html

Provides a mechanism to get translated strings. This class is part of the kiwix::i18n namespace.

```APIDOC
## Class kiwix::i18n::GetTranslatedString

### Description
Provides a mechanism to get translated strings.

### Namespace
kiwix::i18n

```

--------------------------------

### void updateFromXml(const pugi::xml_node &node)

Source: https://libkiwix.readthedocs.io/en/latest/api/classkiwix_1_1Bookmark.html

Updates the bookmark from an XML node.

```APIDOC
## void updateFromXml(const pugi::xml_node &node)

### Description
Updates the bookmark from an XML node.

### Method
Member function

### Signature
`void updateFromXml(const pugi::xml_node &node)`

### Parameters
- **node** (const pugi::xml_node&) - Required - The XML node containing bookmark data.

```

--------------------------------

### Download::cancelDownload

Source: https://libkiwix.readthedocs.io/en/latest/api/classkiwix_1_1Download.html

Cancels the download. A canceled download cannot be resumed and updateStatus does nothing. However, you can still get information based on the last known information.

```APIDOC
## Download::cancelDownload

### Description
Cancels the download. A canceled download cannot be resumed and updateStatus does nothing. However, you can still get information based on the last known information.

### Method
cancelDownload

```

--------------------------------

### Full header file include/book.h defining kiwix::Book class

Source: https://libkiwix.readthedocs.io/en/latest/_sources/api/program_listing_file_include_book.h.rst.txt

This is the complete source code of the book.h header file. It declares the kiwix::Book class, including nested types Illustration and AcquisitionLinks, an enum AcquisitionLinkKind, and all public methods for accessing and modifying book metadata. The file uses include guards and includes standard and project headers.

```cpp
/*
 * Copyright 2011 Emmanuel Engelhart <kelson@kiwix.org>
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU  General Public License as published by
 * the Free Software Foundation; either version 3 of the License, or
 * any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
 * MA 02110-1301, USA.
 */

#ifndef KIWIX_BOOK_H
#define KIWIX_BOOK_H

#include <string>
#include <vector>
#include <memory>
#include <mutex>
#include "common.h"
#include "smartptr.h"

namespace pugi {
class xml_node;
}

namespace zim {
class Archive;
}

namespace kiwix
{

class OPDSDumper;

class Book
{
 public: // types
  class Illustration
  {
    friend class Book;
   public:
    uint16_t getWidth() const;
    uint16_t getHeight() const;
    const std::string getMimeType() const;
    const std::string getUrl() const;
    const std::string getData() const;

    ~Illustration();

   private:
    Illustration();
    Illustration(const Illustration&) = delete;

    struct Impl;
    ValuePtr<Impl> mp_impl;
  };

  typedef std::vector<std::shared_ptr<const Illustration>> Illustrations;

  enum class AcquisitionLinkKind { DIRECT = 0, MAGNET, META4, BITTORRENT, COUNT };

  // Acquisition URLs indexed by AcquisitionLinkKind (empty = not set).
  // Always holds one entry per link kind; its size cannot be changed.
  class AcquisitionLinks
  {
   public:
    AcquisitionLinks();

    size_t size() const { return m_urls.size(); }
    std::string& operator[](size_t i) { return m_urls[i]; }
    const std::string& operator[](size_t i) const { return m_urls[i]; }

   private:
    std::vector<std::string> m_urls;
  };

 public: // functions
  Book();
  Book(const Book& other);
  Book& operator=(const Book& other);
  ~Book();

  bool update(const Book& other);
  void update(const zim::Archive& archive);
  void updateFromXml(const pugi::xml_node& node, const std::string& baseDir);
  void updateFromOpds(const pugi::xml_node& node, const std::string& urlHost, const std::string& baseDir);

  void updateFromOpds(const pugi::xml_node& node, const std::string& urlHost);
  std::string getHumanReadableIdFromPath() const;

  bool readOnly() const;
  std::string getId() const;
  std::string getPath() const;
  bool isPathValid() const;
  std::string getTitle() const;
  std::string getDescription() const;
  std::string getCommaSeparatedLanguages() const;
  const std::vector<std::string> getLanguages() const;
  std::string getCreator() const;
  std::string getPublisher() const;
  std::string getDate() const;

  // Returns the acquisition link of the given kind (empty if not set).
  std::string getUrl(AcquisitionLinkKind linkKind) const;
  std::string getName() const;
  std::string getCategory() const;
  std::string getTags() const;
  std::string getTagStr(const std::string& tagName) const;
  bool getTagBool(const std::string& tagName) const;
  std::string getFlavour() const;
  std::string getOrigId() const;
  uint64_t getArticleCount() const;
  uint64_t getMediaCount() const;
  uint64_t getSize() const;

  Illustrations getIllustrations() const;
  std::shared_ptr<const Illustration> getIllustration(unsigned int size) const;

  std::string getDownloadId() const;

  void setReadOnly(bool readOnly);
  void setId(const std::string& id);
  void setPath(const std::string& path);
  void setPathValid(bool valid);
  void setTitle(const std::string& title);
  void setDescription(const std::string& description);
  void setLanguage(const std::string& language);
  void setCreator(const std::string& creator);
  void setPublisher(const std::string& publisher);
  void setDate(const std::string& date);
  // Sets the acquisition link of the given kind.
  // Setting an empty url string clears the link of that kind.
  void setUrl(AcquisitionLinkKind linkKind, const std::string& url);

```

--------------------------------

### bookmark.h header file with Bookmark class declaration

Source: https://libkiwix.readthedocs.io/en/latest/api/program_listing_file_include_bookmark.h.html

This is the complete header file for the Bookmark class. It includes the license header, include guards, necessary includes, forward declarations, and the class definition with its public and private members. The class uses a pimpl pattern with ValuePtr<Impl> for implementation hiding.

```cpp
/*
 * Copyright 2018 Matthieu Gautier <mgautier@kymeria.fr>
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU  General Public License as published by
 * the Free Software Foundation; either version 3 of the License, or
 * any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
 * MA 02110-1301, USA.
 */

#ifndef KIWIX_BOOKMARK_H
#define KIWIX_BOOKMARK_H

#include <string>
#include "smartptr.h"

namespace pugi {
class xml_node;
}

namespace kiwix
{

class Book;
class Bookmark
{
 public:
  Bookmark();

  Bookmark(const Book& book, const std::string& path, const std::string& title);

  Bookmark(const Bookmark& other);
  Bookmark& operator=(const Bookmark& other);

  ~Bookmark();

  void updateFromXml(const pugi::xml_node& node);

  std::string getBookId() const;
  std::string getBookTitle() const;
  std::string getBookName() const;
  std::string getBookFlavour() const;
  std::string getUrl() const;
  std::string getTitle() const;
  std::string getLanguage() const;
  std::string getDate() const;

  void setBookId(const std::string& bookId);
  void setBookTitle(const std::string& bookTitle);
  void setBookName(const std::string& bookName);
  void setBookFlavour(const std::string& bookFlavour);
  void setUrl(const std::string& url);
  void setTitle(const std::string& title);
  void setLanguage(const std::string& language);
  void setDate(const std::string& date);

 private:
  class Impl;
  ValuePtr<Impl> mp_impl;
};

}

#endif

```

--------------------------------

### bool KiwixServe::isRunning()

Source: https://libkiwix.readthedocs.io/en/latest/api/classkiwix_1_1KiwixServe.html

Checks whether the server is currently running.

```APIDOC
## Method: isRunning

### Description
Checks whether the server is currently running.

### Signature
```cpp
bool isRunning()
```

### Returns
- **bool** - `true` if the server is running, `false` otherwise.

### Usage
```cpp
if (server.isRunning()) { ... }
```
```

--------------------------------

### Server::isRunning() const

Source: https://libkiwix.readthedocs.io/en/latest/api/classkiwix_1_1Server.html

Checks whether the server is currently running.

```APIDOC
## Server::isRunning() const

### Description
Checks whether the server is currently running.

### Returns
- **bool** - True if the server is running, false otherwise.

```

--------------------------------

### Server::getIpMode() const

Source: https://libkiwix.readthedocs.io/en/latest/api/classkiwix_1_1Server.html

Gets the effective IpMode used by this server. The returned value may be different from the one configured via setIpMode(), since the server is expected to adjust to the constraints of the environment (e.g. IpMode::ALL can be converted to IpMode::IPV4 on a system that does not support IPv6).

```APIDOC
## Server::getIpMode() const

### Description
Gets the effective IpMode used by this server. The returned value may be different from the one configured via setIpMode(), since the server is expected to adjust to the constraints of the environment (e.g. IpMode::ALL can be converted to IpMode::IPV4 on a system that does not support IPv6).

### Returns
- **IpMode** - The effective IP mode.

```
Tokens:
Raw