new docs for project
This commit is contained in:
@@ -0,0 +1,162 @@
|
||||
# SeasonalPackDownloader
|
||||
|
||||
## Обзор класса
|
||||
|
||||
`SeasonalPackDownloader` скачивает один архив сезонной сборки в файл. Задача узкая и отдельная по
|
||||
двум причинам: пак — это сотни мегабайт, поэтому он пишется потоком, а не держится в памяти; и его
|
||||
sha256 обязательно сверяется, потому что распаковывать битую загрузку поверх рабочей `.minecraft`
|
||||
нельзя.
|
||||
|
||||
Распаковкой класс не занимается — это делает [BuildSwitcher](BuildSwitcher.md) в отдельном потоке
|
||||
вместе с остальными операциями над содержимым папки игры.
|
||||
|
||||
Набор геттеров прогресса повторяет [VersionInstaller](VersionInstaller.md) и
|
||||
[JavaInstaller](JavaInstaller.md): панель загрузки в интерфейсе читает их одинаково, независимо от
|
||||
того, кто сейчас работает.
|
||||
|
||||
## Место в проекте и зависимости
|
||||
|
||||
Экземпляр создаётся и принадлежит [LauncherBackend](LauncherBackend.md). Адрес архива, его размер
|
||||
и контрольную сумму даёт запись каталога от [SeasonalBuildService](SeasonalBuildService.md).
|
||||
|
||||
Требования сборки: `Qt6::Core` (`QCryptographicHash`, `QSaveFile`, `QTimer`) и `Qt6::Network`
|
||||
(`QNetworkAccessManager`, `QNetworkReply`).
|
||||
|
||||
## Иерархия и роль
|
||||
|
||||
Наследует `QObject`: мета-объектная система, пять сигналов и владение по родителю. Объявлен
|
||||
виртуальный деструктор — класс владеет незавершённой загрузкой и открытым файлом.
|
||||
|
||||
## Публичные методы
|
||||
|
||||
#### explicit SeasonalPackDownloader(QObject \*parent = nullptr)
|
||||
|
||||
Создаёт загрузчик, его `QNetworkAccessManager` и таймер сглаживания прогресса. Конструктор помечен
|
||||
`explicit`.
|
||||
|
||||
#### bool isRunning() const
|
||||
|
||||
Идёт ли загрузка прямо сейчас.
|
||||
|
||||
#### QString label() const
|
||||
|
||||
Подпись загрузки для интерфейса — как правило, название сезонной сборки.
|
||||
|
||||
#### QString stage() const
|
||||
|
||||
Текущий этап словами.
|
||||
|
||||
#### QString currentFile() const
|
||||
|
||||
Файл, который качается сейчас.
|
||||
|
||||
#### qint64 bytesDone() const
|
||||
|
||||
Сколько байт уже получено.
|
||||
|
||||
#### qint64 bytesTotal() const
|
||||
|
||||
Ожидаемый размер архива.
|
||||
|
||||
#### double fraction() const
|
||||
|
||||
Доля выполнения от `0` до `1` либо `-1`, пока итог неизвестен — например, когда сервер не сообщил
|
||||
размер, а в записи каталога он не был указан.
|
||||
|
||||
#### void download(const QUrl &url, const QString &targetPath, const QString &sha256, qint64 expectedSize, const QString &label)
|
||||
|
||||
Скачивает архив по адресу `url` в `targetPath`, сверяя sha256 с переданным значением.
|
||||
|
||||
Файл `targetPath` перезаписывается: недокачанный пак с прошлой попытки не должен пережить новую.
|
||||
Запись идёт через `QSaveFile`, поэтому на месте назначения файл появляется только целиком и только
|
||||
после успешной проверки контрольной суммы.
|
||||
|
||||
Параметр `expectedSize` берётся из записи каталога и используется для расчёта доли выполнения,
|
||||
пока сервер не сообщил размер сам.
|
||||
|
||||
#### void cancel()
|
||||
|
||||
Отменяет загрузку. Недокачанный файл на месте назначения не остаётся.
|
||||
|
||||
## Сигналы
|
||||
|
||||
#### started(const QString &label)
|
||||
|
||||
Загрузка началась. Обработчик показывает панель прогресса.
|
||||
|
||||
#### progressChanged()
|
||||
|
||||
Изменились числа прогресса; испускается не чаще, чем позволяет внутренний таймер, — иначе сигнал
|
||||
на каждый принятый блок обошёлся бы дороже самой загрузки. Обработчик перечитывает геттеры.
|
||||
|
||||
#### finished(const QString &path)
|
||||
|
||||
Архив скачан и проверен; в параметре — путь к готовому файлу.
|
||||
|
||||
Обработчик передаёт этот путь [BuildSwitcher](BuildSwitcher.md) для раскатки поверх содержимого
|
||||
`.minecraft`.
|
||||
|
||||
#### failed(const QString &label, const QString &message)
|
||||
|
||||
Загрузка не удалась: сеть недоступна, сервер ответил ошибкой или не сошлась контрольная сумма.
|
||||
Последний случай особенно важен — он означает, что архив повреждён и распаковывать его нельзя.
|
||||
|
||||
#### canceled(const QString &label)
|
||||
|
||||
Загрузка отменена пользователем.
|
||||
|
||||
## Владение и время жизни
|
||||
|
||||
Класс наследует `QObject` и принимает `parent` — родитель его и удалит.
|
||||
`QNetworkAccessManager` и таймер создаются в конструкторе с загрузчиком в роли родителя.
|
||||
|
||||
Скачиваемый файл хранится как `std::unique_ptr<QSaveFile>`: незавершённая запись отменяется вместе
|
||||
с уничтожением объекта, и повреждённый архив не попадает на место назначения. Сетевой ответ
|
||||
создаётся по ходу работы и закрывается в деструкторе.
|
||||
|
||||
## Потокобезопасность
|
||||
|
||||
Только поток GUI. Данные пишутся на диск блоками по мере поступления, поэтому длительных
|
||||
синхронных операций в потоке нет.
|
||||
|
||||
## Взаимодействие с другими классами
|
||||
|
||||
`LauncherBackend` вызывает `download()` при установке или обновлении сезонной сборки, передавая
|
||||
адрес и контрольную сумму из записи [SeasonalBuildService](SeasonalBuildService.md). Сигналы
|
||||
прогресса он переправляет в те же свойства, что и остальные загрузчики, поэтому панель в главном
|
||||
окне не различает, кто работает.
|
||||
|
||||
По сигналу `finished` бэкенд передаёт путь к архиву в `BuildSwitcher::applyPack()` вместе со
|
||||
списком уходящих файлов из описания предыдущей ревизии.
|
||||
|
||||
## Внешнее взаимодействие
|
||||
|
||||
**Сеть, исходящие запросы.** Одна загрузка по HTTPS с файлового сервера сборок. Направление
|
||||
одностороннее, тело ответа — двоичный архив.
|
||||
|
||||
Данные пишутся потоком через `QSaveFile` с одновременным подсчётом sha256; несовпадение суммы
|
||||
приводит к сигналу `failed`, и файл на месте назначения не появляется. Повторных попыток класс не
|
||||
делает: решение о повторе принимает пользователь.
|
||||
|
||||
Все сигналы приходят в поток GUI.
|
||||
|
||||
## Пример использования
|
||||
|
||||
```cpp
|
||||
auto *packLoader = new SeasonalPackDownloader(this);
|
||||
|
||||
connect(packLoader, &SeasonalPackDownloader::progressChanged, this, &Backend::downloadChanged);
|
||||
connect(packLoader, &SeasonalPackDownloader::finished, this, [this](const QString &path) {
|
||||
m_switcher->applyPack(m_buildId, m_buildName, path,
|
||||
m_previousEntries, m_note, m_gameDir);
|
||||
});
|
||||
connect(packLoader, &SeasonalPackDownloader::failed, this,
|
||||
[this](const QString &, const QString &message) { emit launchError(message); });
|
||||
|
||||
packLoader->download(entry.archiveUrl, targetPath,
|
||||
entry.archiveSha256, entry.archiveSize, entry.name);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
При создании этого документа использовался ИИ.
|
||||
Reference in New Issue
Block a user