168 lines
9.3 KiB
Markdown
168 lines
9.3 KiB
Markdown
# VersionManifestService
|
||
|
||
## Обзор класса
|
||
|
||
Каталог версий Minecraft — это манифест Mojang: около тысячи записей от альф 2010 года до
|
||
свежайших снапшотов. `VersionManifestService` отвечает за него целиком: скачивает манифест,
|
||
кэширует в папке лаунчера и отдаёт из кэша, пока тот не устарел.
|
||
|
||
Класс нужен двум потребителям: окну выбора версии, которому нужен весь список, и установщику,
|
||
которому по идентификатору версии нужна ссылка на её описание.
|
||
|
||
## Место в проекте и зависимости
|
||
|
||
Экземпляр создаётся и принадлежит [LauncherBackend](LauncherBackend.md). Ссылку на него получает
|
||
[VersionInstaller](VersionInstaller.md) — установщик берёт из манифеста адрес описания версии.
|
||
|
||
Путь к файлу кэша даёт `LauncherPaths::versionManifestFile()` из
|
||
[launcherpaths.h](launcherpaths.md).
|
||
|
||
Требования сборки: `Qt6::Core` (`QDateTime`, `QHash`, `QList`, `QUrl`) и `Qt6::Network`
|
||
(`QNetworkAccessManager`).
|
||
|
||
## Иерархия и роль
|
||
|
||
Наследует `QObject`: мета-объектная система, два сигнала и владение по родителю. Виртуальных
|
||
методов базового класса не переопределяет.
|
||
|
||
## Публичные структуры
|
||
|
||
### RemoteVersionEntry
|
||
|
||
Одна строка манифеста Mojang.
|
||
|
||
| Поле | Тип | Описание |
|
||
|------|-----|----------|
|
||
| `id` | `QString` | Идентификатор версии: `1.21.8`, `25w33a`, `b1.7.3` |
|
||
| `type` | `QString` | Категория: `release`, `snapshot`, `old_beta` или `old_alpha` |
|
||
| `url` | `QUrl` | Адрес `<id>.json` с описанием версии |
|
||
| `sha1` | `QString` | Контрольная сумма самого описания |
|
||
| `releaseTime` | `QDateTime` | Дата выпуска; по ней список сортируется новыми вперёд |
|
||
|
||
Категории `type` — те же ключи, по которым окно выбора версии делит каталог на вкладки; версии, не
|
||
попавшие ни в одну из четырёх, интерфейс относит к категории «прочие».
|
||
|
||
## Псевдонимы типов
|
||
|
||
`VersionManifestService::Callback` — `std::function<void(bool ok, const QString &warning)>`.
|
||
Сочетание `ok == true` с непустым `warning` означает особый случай: данные отдали, но из
|
||
устаревшего кэша — сеть недоступна, а показать что-то нужно.
|
||
|
||
## Публичные методы
|
||
|
||
#### explicit VersionManifestService(QObject \*parent = nullptr)
|
||
|
||
Создаёт сервис и его `QNetworkAccessManager`. Манифест при этом не читается — чтение кэша
|
||
откладывается до первого обращения. Конструктор помечен `explicit`.
|
||
|
||
#### QList<RemoteVersionEntry> versions() const
|
||
|
||
Текущий список версий. Возвращает копию; пустой список означает, что данных ещё нет.
|
||
|
||
#### bool hasData() const
|
||
|
||
Есть ли хоть какие-то данные — из сети или из кэша.
|
||
|
||
#### bool isRefreshing() const
|
||
|
||
Идёт ли сейчас сетевое обновление. Интерфейс показывает по этому признаку строку загрузки вместо
|
||
пустого списка.
|
||
|
||
#### QDateTime fetchedAt() const
|
||
|
||
Когда данные были получены. По этой отметке решается, устарел ли кэш.
|
||
|
||
#### std::optional<RemoteVersionEntry> find(const QString &id) const
|
||
|
||
Запись по идентификатору версии; `std::nullopt`, если такой версии в манифесте нет. Из неё
|
||
установщик берёт ссылку на описание версии. Поиск идёт по внутреннему указателю, а не перебором.
|
||
|
||
#### void ensureLoaded(Callback callback, bool forceRefresh = false)
|
||
|
||
Единственная точка входа. Свежий кэш означает отложенный вызов колбэка без обращения к сети; иначе
|
||
запускается один сетевой запрос на всех, кто успел попросить, — колбэки накапливаются и вызываются
|
||
все разом по его завершении.
|
||
|
||
Параметр `forceRefresh` обходит проверку свежести кэша: так работает кнопка принудительного
|
||
обновления.
|
||
|
||
Колбэк вызывается ровно один раз и всегда в потоке GUI, в том числе когда данные уже есть.
|
||
|
||
## Сигналы
|
||
|
||
#### versionsChanged()
|
||
|
||
Список версий изменился — пришли новые данные из сети или прочитан кэш.
|
||
|
||
Обработчик перечитывает `versions()` и обновляет интерфейс. В лаунчере на этот сигнал завязано
|
||
свойство каталога версий, которое читает окно выбора.
|
||
|
||
#### refreshingChanged()
|
||
|
||
Изменился признак сетевого обновления. Обработчик показывает или убирает индикатор загрузки.
|
||
|
||
## Владение и время жизни
|
||
|
||
Класс наследует `QObject` и принимает `parent` — родитель его и удалит.
|
||
`QNetworkAccessManager` создаётся в конструкторе с сервисом в роли родителя.
|
||
|
||
Отложенные колбэки хранятся в списке до завершения текущего запроса. Уничтожение сервиса с
|
||
незавершённым запросом обрывает его вместе с менеджером сети, и накопленные колбэки не
|
||
вызываются.
|
||
|
||
Ссылку на сервис держит установщик версий; уничтожать сервис раньше установщика нельзя.
|
||
|
||
## Потокобезопасность
|
||
|
||
Только поток GUI — так же, как [AuthService](AuthService.md). Чтение и запись кэша выполняются в
|
||
вызывающем потоке, поэтому первое обращение к манифесту делает короткую файловую операцию
|
||
синхронно.
|
||
|
||
## Взаимодействие с другими классами
|
||
|
||
`LauncherBackend` вызывает `ensureLoaded()` при открытии окна выбора версии и по кнопке
|
||
обновления, а сигналы `versionsChanged` и `refreshingChanged` переправляет в свойства, которые
|
||
читает QML. Список из `versions()` он сводит с установленными версиями и отдаёт в интерфейс уже
|
||
готовыми строками.
|
||
|
||
[VersionInstaller](VersionInstaller.md) обращается к `find()`, чтобы получить адрес описания
|
||
версии перед началом загрузки.
|
||
|
||
## Внешнее взаимодействие
|
||
|
||
**Сеть, исходящие запросы.** Класс скачивает манифест версий Mojang через
|
||
`QNetworkAccessManager`. Формат — JSON поверх HTTPS, запрос инициирует лаунчер.
|
||
|
||
Стратегия при недоступной сети встроена в контракт колбэка: если есть устаревший кэш, он
|
||
отдаётся с `ok == true` и заполненным `warning`, и интерфейс показывает список вместо ошибки.
|
||
Полное отсутствие данных даёт `ok == false`.
|
||
|
||
**Файловый кэш.** Манифест сохраняется в файл, путь к которому даёт
|
||
`LauncherPaths::versionManifestFile()`, вместе с отметкой времени получения.
|
||
|
||
Сигналы и колбэки приходят в поток GUI.
|
||
|
||
## Пример использования
|
||
|
||
```cpp
|
||
auto *manifest = new VersionManifestService(this);
|
||
connect(manifest, &VersionManifestService::versionsChanged, this, &Backend::rebuildCatalog);
|
||
|
||
manifest->ensureLoaded([this, manifest](bool ok, const QString &warning) {
|
||
if (!ok) {
|
||
emit catalogError(warning);
|
||
return;
|
||
}
|
||
if (!warning.isEmpty())
|
||
showStatus(warning); // список из устаревшего кэша
|
||
|
||
const auto entry = manifest->find(QStringLiteral("1.21.8"));
|
||
if (entry)
|
||
startDownload(entry->url);
|
||
});
|
||
```
|
||
|
||
---
|
||
|
||
При создании этого документа использовался ИИ.
|