1.3.0.0 이상

설명

파일 압축 다운로드를 시작한다.

파일을 압축을 담당하는 서버 경로를 setCompressURL 메소드를 사용하여 설정하면, 다운로드할 가상 파일들을 하나의 파일로 압축하여 다운로드 한다.

단일/다중 파일 다운로드와 달리, 압축 다운로드는 압축 과정을 서버에 일임하기 때문에, 대상 파일에 대한 다운로드 경로를 지정하는 속성(downUrl 또는 url)에 영향을 받지 않는다.

var dx = dx5.get("component-id");

// 압축 작업을 해야 하는 서버에서 압축 대상을 구별하기 위한 vindex 속성값을 반드시 지정해 주어야 한다.
// vindex는 일종의 유니크한 문자열 값으로써, 가상 파일을 구별하기 위한 유일한 수단이다. 
dx.addVirtualFile({ vindex: "IDX0003", name: "서강대교_509147.jpg", size: 509147 });
dx.addVirtualFile({ vindex: "IDX0004", name: "우도해변_239826.jpg", size: 239826 });
dx.addVirtualFile({ vindex: "IDX0005", name: "코스모스 (빈공간) 195779.jpg", size: 195779 });

// 압축을 처리하고 압축 파일 다운로드 경로를 반환하는 주소를 설정한다.
dx.setCompressURL("http://domain/path/service/compress.do");

// 플래그 값에 따라 다운로드를 수행한다.
// AUTO: 가상 파일을 압축한 후, 다운로드한다.
// SELECTED: 선택된 가상 파일을 압축한 후, 다운로드한다.
// CHECKED: 체크된 가상 파일을 압축한 후, 다운로드한다.
dx.downloadCompressed("SELECTED");

컴포넌트 생성 시점에 btnDownloadCompressedAuto 속성 값을 사용하면 자동으로 바인딩하여 사용할 수 있다.

<button id="btn-download-compressing" type="button">압축 다운로드</button>
<script>
  dx5.create({
    ...,
    // 압축 다운로드 기능이 자동으로 연결된다.
    btnDownloadCompressedAuto: "btn-download-compressing"
  });
</script>

btnDownloadCompressedAuto 속성 외에, btnDownloadCompressedChecked, btnDownloadCompressedSelected를 사용할 수 있다.

DEXTUploadX5는 downloadCompressed 메소드가 호출되면, 압축할 대상들의 vindex 값을 콤마(,) 문자로 연결한 하나의 목록 문자열로 만들고, 'DEXTUploadX5_VIndexes' 이름의 폼데이터에 그 목록 문자열을 POST 형식으로 submit 한다.

서버 웹 애플리케이션은 해당 서버 경로로 요청이 있을 때, 파일 압축을 한 후, 대상 파일을 다운로드할 수 있는 서버 주소를 반환해야 한다.

압축이 서버에서 진행되는 동안은 진행창이 표시되지만, 압축된 파일을 다운로드할 때는 단일 파일 다운로드로 전환되기 때문에 다운로드 과정에 대한 자체 진행창은 제공되지 않는다.

형식

component.downloadCompressed(flag);

파라미터

1.3.0.0 이상

설명

파일 압축을 처리하는 서버 주소를 반환한다.

형식

url = component.getCompressURL();

반환

파일 압축을 처리할 주소

1.3.0.0 이상

설명

파일 압축을 처리하는 서버 주소를 설정한다.

var dx = dx5.get("component-id");

// 압축 작업을 해야 하는 서버에서 압축 대상을 구별하기 위한 vindex 속성값을 반드시 지정해 주어야 한다.
// vindex는 일종의 유니크한 문자열 값으로써, 가상 파일을 구별하기 위한 유일한 수단이다. 
dx.addVirtualFile({ vindex: "IDX0003", name: "서강대교_509147.jpg", size: 509147 });
dx.addVirtualFile({ vindex: "IDX0004", name: "우도해변_239826.jpg", size: 239826 });
dx.addVirtualFile({ vindex: "IDX0005", name: "코스모스 (빈공간) 195779.jpg", size: 195779 });

// 압축을 처리하고 압축 파일 다운로드 경로를 반환하는 주소를 설정한다.
dx.setCompressURL("http://domain/path/service/compress.do");

// 플래그 값에 따라 다운로드를 수행한다.
// AUTO: 가상 파일을 다운로드한다.
// SELECTED: 선택된 가상 파일을 다운로드한다.
// CHECKED: 체크된 가상 파일을 다운로드한다.
dx.downloadCompressed("SELECTED");

서버 웹 애플리케이션은 해당 서버 경로로 요청이 있을 때, 파일 압축을 한 후, 대상 파일을 다운로드할 수 있는 서버 주소를 반환해야 한다.

형식

component.setCompressURL(url);

파라미터

1.3.0.0 이상

설명

파일 압축 요청을 중지한다.

DEXTUploadX5는 컴포넌트 자체에 압축 요청을 중지하는 버튼이나 GUI 요소가 없다.

대신 스크립트를 사용하여 중지할 수 있도록 함수를 제공하고 있다.

<button type="button" onclick="stop('component-id');">중지</button>
<script>
function stop(id) {
  dx5.get(id).stopCompressWaiting();
}
</script>

컴포넌트 생성 시점에 btnStopCompressWaiting 속성 값을 사용하여 자동으로 바인딩하여 사용할 수 있다.

<button id="btn-stop-compresswaiting" type="button">중지</button>
<script>
  dx5.create({
    ...,
    // 압추 요청 중지 기능이 자동으로 연결된다.
    btnStopCompressWaiting: "btn-stop-compresswaiting"
  });
</script>

stopCompressWaiting 메소드는 압축 요청을 중단한다. 압축 과정이 완료된 후, 파일이 다운로드 되는 과정은 취소되지 않는다.

형식

component.stopCompressWaiting();

1.1.0.0 이상

설명

다운로드 되는 파일의 개별 제한 크기를 설정한다. 브라우저 메모리 관리 문제로 인하여 다운로드하는 파일의 크기에 제한을 두었다.

기본값은 100MB이며, 파일 크기를 그 이상 허용하려면 setLimitMultiDownloadSize 메소드를 사용하여 제한된 크기를 변경해 주어야 한다.

// 다운로드 제한 크기를 300MB로 설정한다. 
dx.setLimitMultiDownloadSize(1024 * 1024 * 300);

• 이 함수는 다운로드가 허용되는 파일의 크기를 변경하는 것으로써, 브라우저의 메모리 성능을 향상시키는 것이 아니다. 파일의 크기가 매우 클 경우, 브라우저에 따라 크래시가 발생할 수 있다.
• 4.0.0.0 버전부터는 단일 파일 다운로드 기능에서도 동일하게 적용된다.

형식

component.setLimitMultiDownloadSize(limit);

파라미터

3.8.0.0 이상

설명

다중 파일 다운로드를 할 때, 이어받기 사용 여부를 설정한다. 이어받는 기능은 파일을 다운로드 받는 과정에서 중단되었을 때, 중단된 지점부터 다시 다운로드 받는 기능이다. 그러나 업로드에서의 이어받기와 다르게 다운로드를 취소하거나 창을 닫은 후에, 다시 다운로드를 시작하면 처음부터 다운로드를 받는다.

기본값은 true이다. 만약 서버가 Range 요청을 받아들이지 않는다면 false로 설정하는 것을 권장한다.

function onDX5Created(id) {
    var dx = dx5.get(id);
    // 이어받기 기능을 사용하지 않는다.
    dx.enableResumingDownload(false);
}

3.8.0.0 버전부터 지원하는 이어받기 기능 때문에, 서버로 HEAD 요청을 강제로 보내도록 구현되었다. 이어받기 기능을 비활성하더라도 HEAD 요청은 무조건 발생한다.

형식

component.enableResumingDownload(enable);

파라미터

3.8.0.0 이상

설명

다중 파일 다운로드 작업을 일시 정지한다.

<button type="button" onclick="pause('component-id');">일시 정지</button>
<script>
function pause(id) {
    dx5.get(id).pauseDownloading();
}
</script>

다중 파일 다운로드 작업의 경우만 함수를 사용하여 일시 정지할 수 있다. downloadById 혹은 다운로드 아이콘을 사용하여 대상을 다운로드하는 경우에는 pauseDownloading 함수를 사용해도 작업이 중단되지 않는다.

형식

component.pauseDownloading();

3.8.0.0 이상

설명

정지된 다중 파일 다운로드 작업을 재개한다.

<button type="button" onclick="resume('component-id');">재시도</button>
<script>
function resume(id) {
    dx5.get(id).resumeDownloading();
}
</script>

pauseDownloading 메소드를 사용하여 다운로드 작업을 일시 중지한 상태 또는 오류가 발생하여 일시 중지된 상태에서만 사용할 수 있다.

형식

component.resumeDownloading();

3.8.0.0 이상

설명

다중 파일 다운로드 작업을 위한 다운로드 단위 크기를 설정한다.

다중 파일 다운로드 작업을 할 때, DEXTUploadX5는 파일을 단위 크기 만큼 나누어서 파일을 다운로드한다. 다운로드 단위 크기를 크게 설정하면 다운로드 반복 횟수가 줄고, 반대의 경우에는 다운로드 반복 횟수가 증가한다. 파일을 이어받을 때는 단위 크기가 작을수록 다운로드 작업을 중지할 때 손실되는 데이터 크기가 줄어든다.

// 다운로드할 파일의 크기를 500MB로 제한한다.
dx.setLimitMultiDownloadSize(1024 * 1024 * 500);

// 다운로드 단위 크기를 10MB로 설정한다.
dx.setDownloadBlockSize(1024 * 1024 * 10);

// 다중 파일 다운로드를 시작한다.
dx.download("AUTO", true);

• 적절한 다운로드 단위 크기는 10MB로서 현재 기본값으로 설정되어 있다.
• 단위 크기가 작아지면, 메모리에 부하가 발생할 수 있으므로, 네트워크 환경이 느린 곳에서만 작게 설정하는 것을 권장한다.
• 서버는 반드시 HEAD 요청을 허락해야 한다.
• 서버에서 Range 요청을 허용하지 않는다면 파일을 나누지 않고 한 번에 받는다.

형식

component.setDownloadBlockSize(size);

파라미터

2.0.0.0 이상 4.4.0.0 미만

설명

단일 파일 다운로드를 할 때 HD 응용프로그램을 사용하는지를 반환한다.

형식

using = component.isUsingHDWhenSingle();

반환

단일 파일 다운로드를 할 때 HD 응용프로그램 사용 여부

2.0.0.0 이상 4.4.0.0 미만

설명

단일 파일 다운로드를 할 때 HD 응용프로그램을 사용할 수 있도록 설정하거나 해지한다.

화면상(GUI)에서 다운로드 아이콘을 클릭했을 때 실행되는 단일 파일 다운로드만 해당된다. downloadById 메소드를 사용하는 경우에는 설정과 상관 없이 브라우저 기반 다운로드가 수행된다.

// HD 응용프로그램을 사용하도록 설정한다.
dx.setUsingHDWhenSingle(true);

다운로드할 대상과 동일한 이름을 갖는 항목이 이미 존재할 때, 개발자는 이 항목을 추가(중복)하거나 무시할 수 있도록 콜백 함수(duplicated)를 사용할 수 있다.

dx.setUsingHDWhenSingle(true, function (duplicated) {
    if (confirm(duplicated + " 파일이 이미 존재합니다. 그래도 추가하시겠습니까?")) {
        // return 0; 또는 반환값이 없으면 중복과 상관없이 추가한다.
    } else {
        // 무시한다.
        return 1;
    }
});

반환 값에 따른 내부 처리 방식은 다음과 같는다.

• 1: 항목을 추가하지 않는다.
• 2: 항목을 추가하며, 이후 발생하는 중복 건에 대해서 콜백 호출 없이 자동으로 추가된다.
• 3: 항목을 추가하지 않으며, 이후 발생하는 중복 건에 대해서 콜백 호출 없이 자동으로 무시된다.
• 그 외의 값: 항목을 추가한다.

형식

component.setUsingHDWhenSingle(enable[, funcDuplication]);

파라미터

3.10.0.0 이상

설명

파일 다운로드 작업 사이의 시간 간격 값을 반환한다.

형식

interval = component.getDownloadTimeInterval();

반환

밀리세컨드(1/1000) 단위의 시간 간격 값

3.10.0.0 이상

설명

파일 다운로드 작업 사이의 시간 간격 값을 설정한다.

다중 파일 다운로드는 파일의 개수 및 청크 개수에 따라 다수의 다운로드 작업이 발생하며, 각각 작업마다 주어진 시간 값만큼 지연이 발생한다.

var dx = dx5.get("component-id");
dx.setDownloadTimeInterval(1000);

형식

component.setDownloadTimeInterval(interval);

파라미터

3.10.0.0 이상

설명

서버로 다운로드를 위한 HEAD 요청을 보낼지 여부를 반환한다.

형식

useHead = component.isDownloadHeadRequestEnable();

반환

true/false

3.10.0.0 이상

설명

서버로 다운로드를 위한 HEAD 요청을 보낼지 여부를 설정한다.

제품은 다운로드할 파일의 정보를 얻기 위해서 HEAD 요청을 미리 보낸다. 만약 서버에서 HEAD 요청을 허락하지 않는다면, false로 설정해주어야 한다.

HEAD 요청을 하지 않는 경우, 이어받기 기능을 사용할 수 없으며, 단일 파일 다운로드 경우 서버 오류를 확인하기 어렵다.

var dx = dx5.get("component-id");
dx.setDownloadHeadRequestEnable(false);

형식

component.setDownloadHeadRequestEnable(enable);

파라미터

4.0.0.0 이상

설명

다운로드 방식을 반환한다.

형식

mode = component.getDownloadMode();

반환

'DEFAULT', 'AWSS3', 'NCPOS', 'AZRBS' 중 하나가 반환된다. 기본값은 'DEFAULT'이다.

4.0.0.0 이상

설명

다운로드 방식을 설정한다.

• DEFAULT(기본): 기본으로 지원하는 다운로드 방식을 사용할 때 사용된다.
• AWSS3: Amazon S3로부터 파일을 다운로드할 때 사용된다. 4.0.0.0 이상에서 지원된다.
• NCPOS: NAVER CLOUD PLATFORM Object Storage로부터 파일을 다운로드할 때 사용된다. 4.2.0.0 이상에서 지원된다.
• AZRBS: Azure Blob Storage로부터 파일을 다운로드할 때 사용된다. 4.3.0.0 이상에서 지원된다.

const dx = dx5.get(id);
dx.setDownloadMode("AWSS3");

형식

component.setDownloadMode(mode);

파라미터

4.0.0.0 이상

설명

Amazon S3로부터 파일을 다운로드하기 위한 설정값을 정의한다.

dx.setDownloadMode("AWSS3");
dx.setAWSS3DownloadConfig({
    type: "NON-SECRET",
    accessKeyId: "ABCD...1234",
    secretAccessKey: "ABCD...1234",
    region: "ap-northeast-2",
    bucket: "abc-bucket"
});

형식

component.setAWSS3DownloadConfig(config);

파라미터

dx.setAWSS3DownloadConfig({
    makeKey: item => {
        return item.name;
    }
});

4.2.0.0 이상

설명

NAVER CLOUD PLATFORM Object Storage로부터 파일을 다운로드하기 위한 설정값을 정의한다.

dx.setDownloadMode("NCPOS");
dx.setNCPOSDownloadConfig({
    type: "NON-SECRET",
    accessKeyId: "ABCD...1234",
    secretAccessKey: "ABCD...1234",
    // kr, us, sg, jp, de
    region: "kr",
    bucket: "abc-bucket"
});

형식

component.setNCPOSDownloadConfig(config);

파라미터

dx.setNCPOSDownloadConfig({
    makeKey: item => {
        return item.name;
    }
});

4.3.0.0 이상

설명

AZURE Blob Storage로부터 파일을 다운로드하기 위한 설정값들을 정의한다.

dx.setDownloadMode("AZRBS");
dx.setAZRBSDownloadConfig({
    accountName: "photomanager",
    containerName: "photos",
    sasDownloadURL: "https://example.com/get-download-sastoken.ashx"
});

형식

component.setAZRBSDownloadConfig(config);

파라미터

dx.setAZRBSUploadConfig({
    makeKey: item => {
        return item.name;
    }
});

1.0.0.0 이상

설명

파일 다운로드를 시작한다.

파일을 다운로드하려면 서버에 존재하는 대상의 경로 정보를 얻을 수 있어야 하는데, 가상 파일의 속성을 사용한다.

기본적으로 하나의 가상 파일만 다운로드할 수 있다. 그러므로 flag에 맞는 대상들 중에서 첫번째 파일만 다운로드 대상이 된다. 만일 다중 파일 다운로드(1.1.0.0부터 지원)를 하고자 한다면 useMD 파라미터를 true로 설정하면 다중 파일 다운로드 방식으로 처리가 되며, flag에 맞는 대상 모두가 순차적으로 다운로드 된다.

다운로드는 하려는 가상 파일은 반드시 downUrl 속성에 다운로드할 수 있는 서버 측 주소가 설정되어야 한다. (1.4.1.0 버전부터 url 속성으로도 가능하다.)

대상 경로는 서버의 기능을 사용하여, 반드시 Content-disposition 응답 헤더 값이 attachment 상태이도록 설정되어야 한다.

파일 다운로드의 경우 대상의 존재 유무를 판단하기 위해서 HEAD 메소드 요청을 보내며, HTTP 응답 코드가 오류가 아닌 경우에 다시 다운로드를 수행한다.

<script>
  function onDX5Created(id) {
    var dx = dx5.get(id);
    // 다운로드 경로 정보가 없어서 다운로드할 수 없는 가상 파일이다.
    dx.addVirtualFile({ vindex: "IDX0001", name: "가상파일.txt", size: 12345 });
    // 다운로드 경로가 있으면 다운로드할 수 있다.
    dx.addVirtualFile({ vindex: "IDX0003", name: "서강대교_509147.jpg", size: 509147, downUrl: "http://domain/path/common-download.do?key=FID0001" });
  }
  function download(id) {
    // 플래그 값에 따라 다운로드를 수행한다.
    // AUTO: 첫 번째 가상 파일을 다운로드한다.
    // SELECTED: 선택된 대상 중에 첫 번째 가상 파일을 다운로드한다.
    // CHECKED: 체크된 대상 중에 첫 번째 가상 파일을 다운로드한다.
    dx5.get(id).download("AUTO");
  }
  function multidownload(id) {
    // 플래그 값에 따라 다운로드를 수행한다.
    // AUTO: 모든 가상 파일 항목을 다운로드한다.
    // SELECTED: 선택된 가상 파일 항목 모두를 다운로드한다.
    // CHECKED: 체크된 가상 파일 항목 모두를 다운로드한다.
    dx5.get(id).download("AUTO", true);
  }
</script>
<button type="button" onclick="download('component-id');">단일 파일 다운로드</button>
<button type="button" onclick="multidownload('component-id');">다중 파일 다운로드</button>

download 메소드를 사용할 때, 1.0.0.0 버전과 차이점이 존재한다. 단일 파일 다운로드의 경우, 1.0.0.0 버전에서는 flag 값에 해당하는 대상이 downUrl이 명시가 되지 않는 경우, 다운로드가 취소가 되었지만, 1.1.0.0 버전에서는 flag 값에 해당하는 대상이 downUrl이 명시가 되지 않았다면, 다음의 적합한 대상을 찾는다. 그러므로 정확히 지정된 대상을 다운로드하려면, download가 아니라 downloadById를 사용하는 것을 권장한다.

1.1.0.0 버전부터 추가된 다중 파일 다운로드 기능은 플러그인 기술을 사용하지 않고 순수 브라우저의 기능만으로 구현되었다. 플러그인을 사용한 다운로드처럼, 진행창을 제공은 하지만, 브라우저가 최종적으로 파일을 저장하는 단계(제품이 관여할 수 없는)가 존재하기 때문에, 다운로드가 완료되었다하더라도, 브라우저에서 질의하는 메시지들이 보여질 수 있다. 더불어 macOS 환경에서는 Safari 브라우저의 경우 10.1 버전 이상만 지원한다. 그리고 iOS, iPad 환경에서는 Safari 브라우저가 17 버전 이상인 경우 다중 파일 다운로드를 지원(10개 이하의 파일만 가능하다.)한다.

<script>
  function onDX5Created(id) {
    var dx = dx5.get(id);
    // 다운로드 경로 정보가 없어서 다운로드할 수 없는 가상 파일이다.
    dx.addVirtualFile({ vindex: "IDX0001", name: "가상파일.txt", size: 12345 });
    // 다운로드 경로가 있으면 다운로드할 수 있다.
    dx.addVirtualFile({ vindex: "IDX0003", name: "서강대교_509147.jpg", size: 509147, url: "http://domain/path/common-download.do?key=FID0001" });
  }
  function download(id) {
    // 플래그 값에 따라 다운로드를 수행한다.
    // AUTO: 모든 가상 파일 항목을 다운로드한다.
    // SELECTED: 선택된 가상 파일 항목 모두를 다운로드한다.
    // CHECKED: 체크된 가상 파일 항목 모두를 다운로드한다.
    dx5.get(id).download("AUTO");
  }
</script>
<button type="button" onclick="download('component-id');">다운로드</button>

형식

// 1.1.0.0 이상 
object.download(flag[, useMD]);

파라미터

1.0.0.0 이상

설명

주어진 고유 아이디에 해당하는 가상 파일을 다운로드한다.

파일을 다운로드하려면 서버에 존재하는 대상의 경로 정보를 얻을 수 있어야 하는데, 가상 파일의 속성을 사용한다.

다운로드는 하려는 가상 파일은 반드시 downUrl 속성에 다운로드할 수 있는 서버 측 주소가 설정되어야 한다.(1.4.1.0 버전부터 url 속성으로도 가능하다.)

<script>
  function onDX5Created(id) {
    var dx = dx5.get(id);
    // 다운로드 경로 정보가 없어서 다운로드할 수 없는 가상 파일이다.
    dx.addVirtualFile({ vindex: "IDX0001", name: "가상파일.txt", size: 12345 });
    // 다운로드 경로가 있으면 다운로드할 수 있다.
    dx.addVirtualFile({ vindex: "IDX0003", name: "서강대교_509147.jpg", size: 509147, downUrl: "http://domain/path/common-download.do?key=FID0001" });
  }
  function download(id) {
    var dx = dx5.get(id);
    // 두 번째 가상 파일을 선택한다.
    var itemId = dx.getItemId(1);
    dx.downloadById(itemId);
  }
</script>
<button type="button" onclick="download('component-id');">다운로드</button>

다운로드 경로는 서버 측 컴포넌트를 사용하여, 반드시 Content-disposition 응답 헤더 값이 attachment 상태이어야 한다.

더불어 대상의 존재 유무를 판단하기 위해서 HEAD 메소드 요청을 보내며, HTTP 응답 코드가 오류가 아닌 경우에 다시 다운로드를 수행한다.

<script>
  function onDX5Created(id) {
    var dx = dx5.get(id);
    // 다운로드 경로 정보가 없어서 다운로드할 수 없는 가상 파일이다.
    dx.addVirtualFile({ vindex: "IDX0001", name: "가상파일.txt", size: 12345 });
    // 다운로드 경로가 있으면 다운로드할 수 있다.
    dx.addVirtualFile({ vindex: "IDX0003", name: "서강대교_509147.jpg", size: 509147, url: "http://domain/path/common-download.do?key=FID0001" });
  }
  function download(id) {
    var dx = dx5.get(id);
    // 두 번째 가상 파일을 선택한다.
    var itemId = dx.getItemId(1);
    dx.downloadById(itemId);
  }
</script>
<button type="button" onclick="download('component-id');">다운로드</button>

형식

component.downloadById(id);

파라미터

2.0.0.0 이상 4.4.0.0 미만

설명

주어진 고유 아이디에 해당하는 가상 파일을 HD 응용프로그램을 사용하여 다운로드한다.

파일을 다운로드하려면 서버에 존재하는 대상의 경로 정보를 얻을 수 있어야 하는데, 가상 파일의 속성을 사용한다.

가상 파일은 url 속성에 다운로드할 수 있는 서버 측 주소가 설정되어야 한다.

1.4.1.0 버전부터 downUrl, url 두 속성을 사용할 수 있다.

<script>
    function onDX5Created(id) {
        var dx = dx5.get(id);
        // 다운로드 경로 정보가 없어서 다운로드할 수 없는 가상 파일이다.
        dx.addVirtualFile({ vindex: "IDX0001", name: "가상파일.txt", size: 12345 });
        // 다운로드 경로가 있으면 다운로드할 수 있다.
        dx.addVirtualFile({ vindex: "IDX0003", name: "서강대교_509147.jpg", size: 509147, url: "http://domain/path/common-download.do?key=FID0001", chunkSize: 10 });
    }
    function download(id) {
        var dx = dx5.get(id);
        // 두 번째 가상 파일을 선택한다.
        var itemId = dx.getItemId(1);
        dx.downloadByIdToHD(itemId);
    }
</script>
<button type="button" onclick="download('component-id');">다운로드</button>

HD 응용프로그램을 사용하여 다운로드를 할 때에는 다운로드 요청에 대한 서버의 Content-disposition 응답 헤더가 attachement 혹은 inline인 경우와 상관 없이 강제로 파일을 다운로드할 수 있다.

다운로드할 대상과 동일한 이름을 갖는 항목이 이미 존재할 때, 개발자는 이 항목을 추가(중복)하거나 무시할 수 있도록 콜백 함수(duplicated)를 사용할 수 있다.

var dx = dx5.get(id);
// 두 번째 가상 파일을 선택한다.
var itemId = dx.getItemId(1);
dx.downloadByIdToHD(itemId, function (fileName) {
    if (confirm(fileName + " 파일이 이미 존재한다. 그래도 추가하시겠습니까?")) {
        // return 0; 또는 반환값이 없으면 중복과 상관없이 추가한다.
    } else {
        // 무시한다.
        return 1;
    }
});

반환 값에 따른 내부 처리 방식은 다음과 같는다.

• 1: 항목을 추가하지 않는다.
• 2: 항목을 추가하며, 이후 발생하는 중복 건에 대해서 콜백 호출 없이 자동으로 추가된다.
• 3: 항목을 추가하지 않으며, 이후 발생하는 중복 건에 대해서 콜백 호출 없이 자동으로 무시된다.
• 그 외의 값: 항목을 추가한다.

형식

component.downloadByIdToHD(id[, duplicated]);

파라미터

2.0.0.0 이상 4.4.0.0 미만

설명

HD 응용프로그램을 사용하여 다중 파일 다운로드를 시작한다.

파일을 다운로드하려면 서버에 존재하는 대상의 경로 정보를 얻을 수 있어야 하는데, 가상 파일의 속성을 사용한다.

다운로드는 하려는 가상 파일은 반드시 url 속성에 다운로드할 수 있는 서버 측 주소가 설정되어야 한다.

1.4.1.0 버전부터 downUrl, url 두 속성을 사용할 수 있다.

<script>
    function onDX5Created(id) {
        var dx = dx5.get(id);
        // 다운로드 경로 정보가 없어서 다운로드할 수 없는 가상 파일이다.
        dx.addVirtualFile({ vindex: "IDX0001", name: "가상파일.txt", size: 12345 });
        // 다운로드 경로가 있으면 다운로드할 수 있다.
        dx.addVirtualFile({ vindex: "IDX0003", name: "서강대교_509147.jpg", size: 509147, url: "http://domain/path/common-download.do?key=FID0001", chunkSize: 10 });
    }
    function download(id) {
        // 플래그 값에 따라 다운로드를 수행한다.
        // AUTO: 가상 파일들을 다운로드한다.
        // SELECTED: 선택된 가상 파일들을 다운로드한다.
        // CHECKED: 체크된 가상 파일들을 다운로드한다.
        dx5.get(id).downloadToHD("AUTO");
    }
</script>
<button type="button" onclick="download('component-id');">파일 다운로드</button>

특별한 코드 처리없이 "AUTO" 파라미터 값을 가지고 업로드를 처리하려 한다면, 컴포넌트 생성 시점에 btnDownloadToHDAuto 속성 값을 사용하여 자동으로 바인딩하여 사용할 수 있다.

<button id="btn-download" type="button">다운로드</button>
<script>
    dx5.create({
        ...,
        // 파일 다운로드 기능이 자동으로 연결된다.
        btnDownloadToHDAuto: "btn-download"
    });
</script>

btnDownloadToHDAuto 속성 외에, btnDownloadToHDSelected, btnDownloadToHDChecked를 사용할 수 있다.

다운로드할 대상과 동일한 이름을 갖는 항목이 이미 존재할 때, 개발자는 이 항목을 추가(중복)하거나 무시할 수 있도록 콜백 함수(duplicated)를 사용할 수 있다.

var dx = dx5.get(id);
dx.downloadToHD("AUTO", function (fileName) {
    if (confirm(fileName + " 파일이 이미 존재한다. 그래도 추가하시겠습니까?")) {
        // return 0; 또는 반환값이 없으면 중복과 상관없이 추가한다.
    } else {
        // 무시한다.
        return 1;
    }
});

반환 값에 따른 내부 처리 방식은 다음과 같는다.

• 1: 항목을 추가하지 않는다.
• 2: 항목을 추가하며, 이후 발생하는 중복 건에 대해서 콜백 호출 없이 자동으로 추가된다.
• 3: 항목을 추가하지 않으며, 이후 발생하는 중복 건에 대해서 콜백 호출 없이 자동으로 무시된다.
• 그 외의 값: 항목을 추가한다.

버튼에 자동으로 바인딩을 하여 사용할 경우에는 중복 처리를 위한 콜백 함수를 적용할 수 없다.

형식

component.downloadToHD(flag[, duplicated]);

파라미터

2.0.0.0 이상 4.4.0.0 미만

설명

HD 응용프로그램에 설정된 다운로드 경로를 반환한다.

dx.getDownloadPathOfHD(function (path) {
  // HD 응용프로그램의 다운로드 경로이다.
  console.log(path);
});

HD 응용프로그램을 사용하는 경우에 사용될 메소드들은 대부분 내부적으로 비동기 작업을 수행한다. 비동기를 작업을 수행하기 때문에 반환 값을 받기 전까지 스레드가 대기하지 않으며, 요청에 대한 결과 값을 받기 위해서 콜백 함수를 이용해야 한다.

형식

component.getDownloadPathOfHD(success);

파라미터

2.0.0.0 이상 4.4.0.0 미만

설명

다운로드 경로를 설정한다.

// 드라이브 문자열로 시작하면 절대 경로가 설정된다.
dx.setDownloadPathOfHD("c:\\temp");
// <home> 문자열로 시작하면 사용자 폴더 하위 경로가 설정된다.
dx.setDownloadPathOfHD("<home>\\temp");
// <doc> 문자열로 시작하면 문서 폴더 하위 경로가 설정된다.
dx.setDownloadPathOfHD("<doc>\\temp");
// <desktop> 문자열로 시작하면 바탕화면 폴더 하위 경로가 설정된다.
dx.setDownloadPathOfHD("<desktop>\\temp");
// <downloads> 문자열로 시작하면 다운로드 폴더 하위 경로가 설정된다. (2.5.0.0 버전부터 지원)
dx.setDownloadPathOfHD("<downloads>\\temp");

만일 다운로드 경로를 변경한 후, 그 변경 값을 바로 알고 싶다면 콜백 함수(success)를 사용해야 한다.

dx.setDownloadPathOfHD("<doc>\\temp", function (path) {
  console.log(path);
});

HD 응용프로그램을 사용하는 경우에 사용될 메소드들은 대부분 내부적으로 비동기 작업을 수행한다. 비동기를 작업을 수행하기 때문에 작업 처리 결과를 받기 전까지 스레드가 대기하지 않으며, 요청에 대한 결과 값을 받기 위해서 콜백 함수를 이용해야 한다.

형식

component.setDownloadPath(path[, success]);

파라미터

1.0.0.0 이상

설명

현재 다운로드 상태 정보를 갖는 객체를 반환한다.

파일이 다운로드 중인 과정에 사용하면, 업로드 상태 정보를 알아낼 수 있다.

이 함수를 사용하여 반환된 객체는 시간에 따라 다른 값을 갖는 것이 아니라, 함수 호출 시점의 상태를 복사한 값만 갖는다.

다운로드하는 과정의 변화를 계속 얻으려면 setTimeout과 같은 함수를 사용해야 한다.

function toggleDownloadStatus(isBegin) {
  function downloadProgress() {			
    var dx = dx5.get("dext5"), 
        out = document.getElementById("downstatus-value"), 
        status = dx.getDownloadStatus();
    out.innerHTML = "" + 
      "name: " + status.currentName + "<br/>" + 
      "speed: " + status.totalSpeed + "(sec)<br/>" + 
      "count(completed/total): " + status.completeCount + "/" + status.totalCount + "<br/>" + 
      "current rate: " + status.currentRate + " % <br/>" + 
      "current size(received/total): " + status.currentReceiveSize + "/" + status.currentSize + " (bytes)<br/>" + 
      "current time(past/remained): " + status.currentTime + "/" + status.remainedCurrentTime + "<br/>" + 
      "total rate: " + status.totalRate + " % <br/>" + 
      "total size(received/total): " + status.totalReceiveSize + "/" + status.totalSize + " (bytes)<br/>" + 
      "total time(past/remained): " + status.totalTime + "/" + status.remainedTotalTime + "<br/>" + 
      "";
    if (window.isDownloading === true) {
      setTimeout(downloadProgress, 1000);
    }
  }
  window.isDownloading = isBegin;
  if (isBegin) downloadProgress();
}

형식

status = component.getDownloadStatus();

반환

다운로드 전송 상태 값을 갖는 객체

다음은 객체가 갖는 속성에 대한 설명이다.

2.0.0.0 이상 4.4.0.0 미만

설명

HD 응용프로그램의 다운로드 폴더를 변경하기 위해 폴더 선택 다이얼로그 창을 띄웁니다.

여러개 파일을 다운로드하기 때문에, 다운로드할기 전에 다운로드할 위치를 설정해야 한다.

다운로드 위치를 변경하지 않는다면 기본 위치(문서 폴더 하위 DEXTUploadX5 HDM 폴더)가 사용된다.

function changePath(id) {
  var dx = dx5.get(id);
  dx.openDownloadPathDialogOfHD();
}

openDownloadPathDialogOfHD 메소드는 사용자에게 다운로드 경로를 선택할 기회를 주는 용도로 사용된다.

다운로드 경로가 변경이 되면 콜백 함수를 사용하여 변경된 경로를 얻을 수 있다.

function changePath(id) {
  var dx = dx5.get(id);
  dx.openDownloadPathDialogOfHD(function (path) {
    // 변경된 다운로드 경로를 얻을 수 있다.
    console.log(path);
  });
}

형식

component.openDownloadPathDialogOfHD([success]);

파라미터

2.4.0.0 이상 4.4.0.0 미만

설명

HD 응용프로그램에 설정된 옵션 정보를 콜백 함수로 반환한다.

dx.getOptionsOfHD(function (option) {
  // option 파라미터는 HD 응용프로그램의 옵션 정보를 가지고 있는 JSON 객체이다.
});

옵션 객체는 다음과 같다.

{
	// 파일이 추가되면 프로그램 자동으로 활성화
	autoActivation: true,
	// 파일이 추가되면 자동으로 다운로드를 시작
	autoDownload: true,
	// 파일을 삭제하면 로컬에 남겨진 임시 파일 정보도 함께 삭제
	deleteTemporary: false,
	// 다운로드가 중단된 파일 있을 때, 프로그램이 활성화되면 바로 다운로드 시작
	resumeDownload: true,
	// 파일이 다운로드될 때, 프로그램이 닫히더라도 임시 정보로 남겨지는 항목 대상
	saveStatus: {
		// 대기 또는 중지된 항목
		waitStop: true,
		// 다운로드 중이었던 항목
		downloading: true,
		// 다운로드가 완료된 항목
		complete: true,
		// 오류가 발생한 항목
		error: true
	}
}

형식

component.getOptionsOfHD(success);

파라미터

2.4.0.0 이상 4.4.0.0 미만

설명

HD 응용프로그램의 옵션을 한 번에 설정한다.

dx.setOptionsOfHD({
	autoActivation: true,
	autoDownload: true,
	deleteTemporary: false,
	resumeDownload: true,
	saveStatus: {
		waitStop: true,
		downloading: true,
		complete: true,
		error: true
	}
}, function () { ... });

형식

component.setOptionsOfHD(option[, success]);

파라미터

{
	// 파일이 추가되면 프로그램 자동으로 활성화
	autoActivation: true,
	// 파일이 추가되면 자동으로 다운로드를 시작
	autoDownload: true,
	// 파일을 삭제하면 로컬에 남겨진 임시 파일 정보도 함께 삭제
	deleteTemporary: false,
	// 다운로드가 중단된 파일 있을 때, 프로그램이 활성화되면 바로 다운로드 시작
	resumeDownload: true,
	// 프로그램이 닫히더라도 유지되는 항목 대상
	saveStatus: {
		// 대기 또는 중지된 항목
		waitStop: true,
		// 다운로드 중이었던 항목
		downloading: true,
		// 다운로드가 완료된 항목
		complete: true,
		// 오류가 발생한 항목
		error: true
	}
}

2.4.0.0 이상 4.4.0.0 미만

설명

자동 활성화 옵션 값을 설정한다

자동 활성화란 다운로드 하고자 하는 파일 항목을 HD 응용프로그램에 등록했을 때, HD 응용 프로그램을 활성 상태로 바꾸는 것을 말한다. 이 값이 true이면, 숨겨져 있던 응용 프로그램이 창 모드로 보이게 된다.

// 자동 활성화 옵션을 true로 변경한다.
dx.setAutoActivationOptionOfHD(true, function () {
    ...
});

형식

component.setAutoActivationOptionOfHD(value[, success]);

파라미터

2.4.0.0 이상 4.4.0.0 미만

설명

자동 다운로드 옵션 값을 설정한다.

자동 다운로드란 다운로드 하고자 하는 파일 항목을 HD 응용프로그램에 등록했을 때, HD 응용 프로그램을 대상을 바로 다운로드하는 것을 말한다.

// 자동 다운로드 옵션을 true로 변경한다.
dx.setAutoDownloadOptionOfHD(true, function () {
    ...
});

형식

component.setAutoDownloadOptionOfHD(value[, success]);

파라미터

2.4.0.0 이상 4.4.0.0 미만

설명

임시 파일 삭제 옵션 값을 설정한다.

임시 파일 삭제란 응용 프로그램에서 다운로드 항목들을 삭제할 때, 항목의 임시 파일도 함께 삭제하는 것을 말한다. 파일 다운로드을 시작하고 난 후, 다운로드가 완료되지 않으면 항상 임시 파일이 남아있다.

// 임시 파일 삭제 옵션을 true로 변경한다.
dx.setDeleteTemporaryOptionOfHD(true, function () {
    ...
});

형식

component.setDeleteTemporaryOptionOfHD(value[, success]);

파라미터

2.4.0.0 이상 4.4.0.0 미만

설명

재(다시) 다운로드 옵션 값을 설정한다.

재(다시) 다운로드란 다운로드가 완료되지 않은 항목이 있는 상태에서 프로그램이 종료된 후, 다시 프로그램이 실행이 되면, 완료되지 않은 대상 파일을 자동으로 다운로드한다.

// 재(다시) 다운로드 옵션을 true로 변경한다.
dx.setResumeDownloadOptionOfHD(true, function () {
    ...
});

형식

component.setResumeDownloadOptionOfHD(value[, success]);

파라미터

2.4.0.0 이상 4.4.0.0 미만

설명

종료 후 유지 대상 옵션 값을 설정한다.

종료 후 유지 대상이란 프로그램이 종료된 후, 다시 프로그램이 실행이 되었을 때, 유지할 항목을 가리킨다.

// 종료 후 유지 대상을 변경한다.
dx.setSaveStatusOptionOfHD(15, function () {
    ...
});

downloading 값(2)이 누락된다면, 재(다시) 다운로드 옵션 설정에 영향을 받는 항목이 없기 때문에, 자동으로 다운로드할 항목이 유지되지 않는다.

형식

component.setSaveStatusOptionOfHD(value[, success]);

파라미터

1.1.0.0 이상

설명

파일 다운로드를 중지한다.

DEXTUploadX5는 컴포넌트 자체에 다운로드를 중지하는 버튼이나 GUI 요소가 없다.

대신 스크립트를 사용하여 중지할 수 있도록 함수를 제공하고 있다.

<button type="button" onclick="stop('component-id');">중지</button>
<script>
function stop(id) {
  dx5.get(id).stopDownloading();
}
</script>

컴포넌트 생성 시점에 btnStopDownloading 속성 값을 사용하여 자동으로 바인딩하여 사용할 수 있다.

<button id="btn-stop-downloading" type="button">중지</button>
<script>
  dx5.create({
    ...,
    // 다운로드 중지 기능이 자동으로 연결된다.
    btnStopDownloading: "btn-stop-downloading"
  });
</script>

다중 파일 다운로드 작업만 중단할 수 있다. downloadById 혹은 다운로드 아이콘을 사용하여 대상을 다운로드하는 경우에는 stopDownloading 함수를 사용해도 작업이 중단되지 않는다.

형식

component.stopDownloading();