3. コンテンツダウンロード

Kollus SDK を通じたコンテンツダウンロードは、常に 2 つのステップを経て進行します。 まず URL からコンテンツのメタ情報を読み込んでメディアコンテンツキー（MediaContentKey、mck）を取得した後、そのキーを基に実際のファイルダウンロードを開始します。

このドキュメントのすべてのサンプルコードは、公式サンプルアプリ kollus_player_v2_android を基に作成されています。

ダウンロードフロー

// DownloadService.LoadTask.run()
KollusContent content = mInfo.getMultiKollusContent().getKollusContent();
String extraDrmParam = null;   // Dynamic DRM parameter (null if not needed)

// Step 1: Load content metadata (synchronous)
int nErrorCode = mInfo.getKollusStorage().load(mInfo.getUrl(), extraDrmParam, content);
if (nErrorCode != ErrorCodes.ERROR_OK) {
    // Load failed: ERROR_STORAGE_FULL, ERROR_INCORRECT_AUTH_KEY, ERROR_EXPIRATION_*
    return;
}

// Step 2: Start actual download based on media content key
int nRet = mInfo.getKollusStorage().download(content.getMediaContentKey());
if (nRet >= 0) {
    // Download started successfully: the onProgress callback loop begins.
} else {
    // Download start failed: nRet value indicates the error code.
}

デバイスの空き容量確認

ダウンロード開始前に、デバイスの空き容量がコンテンツファイルサイズと最小空き容量（例: 150MB）の合計値以上であることを確認します。

long freeSize = Utils.getAvailableMemorySize(mStoragePath) - content.getFileSize();
if (freeSize < MIN_FREE_SIZE) {   // Official sample policy: 150MB
    // Handle ERROR_STORAGE_FULL when insufficient free space
    return;
}

ダウンロードのキャンセル・一時停止・再開の制御ポリシー

動作	API	説明
ダウンロード開始	storage.download(mck)	nRet が 0 以上であれば正常に進行し、負の値であればエラーを示します。
ダウンロードキャンセル	storage.unload(mck)	ダウンロードセッションを完全に中断し、一時保存されていた部分ファイルも削除します。
ダウンロード一時停止	専用 API なし	明示的な Resume API が提供されていないため、unload を呼び出してキャンセル後に再開します。SDK が内部的に一部データを保持する場合がありますが、一般的には最初からダウンロードし直すことを想定してください。
ダウンロード再開	再度 download(mck) を呼び出す	-

サンプルアプリケーションの制御モデル

公式サンプルアプリは、別途の一時停止および再開 UI コンポーネントを構成せず、キャンセル後に再開する構造を採用しています。

ダウンロード進行率の追跡

リアルタイムのダウンロード進行状況は、onProgress イベント内部に注入される KollusContent インスタンスのプロパティを参照して追跡します。 詳細については、8. ダウンロードイベント/コールバック ドキュメントを参照してください。

API	説明
KollusContent.getFileSize()	コンテンツファイルサイズ
KollusContent.getReceivingSize()	受信済みサイズ
KollusContent.getDownloadPercent()	ダウンロード進行率（0〜100）
KollusContent.isDownloadCompleted()	ダウンロード完了かどうか

初期ダウンロード進行率が 0 で返される場合、以下のように明示的に計算式を実装してリアルタイムの進行率情報を補正できます。

long percent = content.getDownloadPercent();
if (content.getFileSize() > 0) {
    percent = content.getReceivingSize() * 100 / content.getFileSize();
}

同一コンテンツの重複ダウンロード防止

特定のコンテンツに対して download(mck) がすでに実行中、またはダウンロードが完了した状態で呼び出された場合、以下のエラーが返されます。

• ERROR_ALREADY_DOWNLOADING: 現在ダウンロードが進行中の状態
• ERROR_ALREADY_DOWNLOADED: ダウンロードがすでに完了した状態

新しいダウンロード API を呼び出す前に、現在ダウンロード済みのコンテンツリストを先に照会することを推奨します。詳細については、4. ダウンロードリスト管理 ドキュメントを参照してください。