3. 콘텐츠 다운로드

Kollus SDK를 통한 콘텐츠 다운로드는 항상 두 단계를 거쳐 진행됩니다. 먼저 URL에서 콘텐츠 메타 정보를 로드하여 미디어 콘텐츠 키(MediaContentKey, mck)를 확보한 뒤, 해당 키를 기반으로 실제 파일 다운로드를 시작합니다.

이 문서의 모든 예제 코드는 공식 샘플 앱인 kollus_player_v2_android를 바탕으로 작성되었습니다.

---

다운로드 흐름

// DownloadService.LoadTask.run()
KollusContent content = mInfo.getMultiKollusContent().getKollusContent();
String extraDrmParam = null;   // 동적 DRM 파라미터 (불필요한 경우 null)

// Step 1: 콘텐츠 메타 정보 로드 (동기)
int nErrorCode = mInfo.getKollusStorage().load(mInfo.getUrl(), extraDrmParam, content);
if (nErrorCode != ErrorCodes.ERROR_OK) {
    // 로드 실패: ERROR_STORAGE_FULL, ERROR_INCORRECT_AUTH_KEY, ERROR_EXPIRATION_*
    return;
}

// Step 2: 미디어 콘텐츠 키 기반 실제 다운로드 시작
int nRet = mInfo.getKollusStorage().download(content.getMediaContentKey());
if (nRet >= 0) {
    // 다운로드 시작 성공: onProgress 콜백 루프가 시작됩니다.
} else {
    // 다운로드 시작 실패: nRet 값이 에러 코드를 의미합니다.
}

---

디바이스 가용 용량 확인

다운로드 시작 전 디바이스 가용 용량이 콘텐츠 파일 크기와 최소 여유 공간(예: 150MB)의 합산 값 이상인지 확인합니다.

long freeSize = Utils.getAvailableMemorySize(mStoragePath) - content.getFileSize();
if (freeSize < MIN_FREE_SIZE) {   // 공식 샘플 정책: 150MB
    // 여유 공간 부족 시 ERROR_STORAGE_FULL 처리
    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. 다운로드 목록 관리 문서를 참고하세요.