DownloadFileChunk API¶

Downloads a single chunk of a staged file using an open download handler. Returns the chunk bytes as base64-encoded content inside an XML element, along with metadata about the chunk and the total file. This is the second step in the chunked download workflow.

Endpoint¶

/srv.asmx/DownloadFileChunk

Methods¶

• GET /srv.asmx/DownloadFileChunk?authenticationTicket=...&DownloadHandler=...&StartOffset=...&ChunkSize=...

• POST /srv.asmx/DownloadFileChunk (form data)

• SOAP Action: http://tempuri.org/DownloadFileChunk

Parameters¶

Response¶

Success Response¶

The chunk bytes are returned as base64-encoded text in the XML element body. File metadata and chunk integrity information are provided as attributes.

<response success="true"

          filelength="1048576"

          chunklength="65536"

          lastchunk="false"

          chunkCRC32="a3f1c29d">

  JVBERi0xLjQKJeLjz9MKNiAwIG9iag==...

</response>

Error Response¶

<response success="false" error="Error message" />

Required Permissions¶

Any authenticated user may call this API. The download handler must have been created by the same authenticated user's session.

Chunked Download Workflow¶

1. GetDownloadHandler (or GetDownloadHandlerByVersion / DownloadZipWithHandler) -" Prepare the file and obtain a DownloadHandler GUID and the total file size.

2. DownloadFileChunk (this API) -" Call repeatedly, advancing StartOffset by chunklength after each response, until lastchunk="true".

3. DeleteDownloadHandler -" Clean up the handler and its temporary file.

Iteration Example¶

// First chunk

StartOffset=0, ChunkSize=65536

-' chunklength=65536, lastchunk="false"

// Second chunk

StartOffset=65536, ChunkSize=65536

-' chunklength=65536, lastchunk="false"

// Final chunk (file size = 180000 bytes)

StartOffset=131072, ChunkSize=65536

-' chunklength=48928, lastchunk="true"  --- stop here

Always advance StartOffset by chunklength (not ChunkSize) to correctly handle the shorter final chunk.

Example¶

GET Request¶

GET /srv.asmx/DownloadFileChunk

  ?authenticationTicket=3f2504e0-4f89-11d3-9a0c-0305e82c3301

  &DownloadHandler=a1b2c3d4-e5f6-7890-abcd-ef1234567890

  &StartOffset=0

  &ChunkSize=65536

HTTP/1.1

POST Request¶

POST /srv.asmx/DownloadFileChunk HTTP/1.1

Content-Type: application/x-www-form-urlencoded

authenticationTicket=3f2504e0-4f89-11d3-9a0c-0305e82c3301

&DownloadHandler=a1b2c3d4-e5f6-7890-abcd-ef1234567890

&StartOffset=0

&ChunkSize=65536

SOAP Request¶

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"

               xmlns:tns="http://tempuri.org/">

  <soap:Body>

    <tns:DownloadFileChunk>

      <tns:authenticationTicket>3f2504e0-4f89-11d3-9a0c-0305e82c3301</tns:authenticationTicket>

      <tns:DownloadHandler>a1b2c3d4-e5f6-7890-abcd-ef1234567890</tns:DownloadHandler>

      <tns:StartOffset>0</tns:StartOffset>

      <tns:ChunkSize>65536</tns:ChunkSize>

    </tns:DownloadFileChunk>

  </soap:Body>

</soap:Envelope>

JavaScript¶

Every call answers XML with HTTP 200, success or not, so success is the thing to branch on and errorCode is the number to report.

async function call(action, params) {
  const response = await fetch(`/srv.asmx/${action}?${new URLSearchParams(params)}`);
  const root = new DOMParser()
    .parseFromString(await response.text(), 'text/xml')
    .documentElement;

  if (root.getAttribute('success') !== 'true') {
    throw new Error(`${root.getAttribute('errorCode')}: ${root.getAttribute('error')}`);
  }
  return root;
}

Reads one piece of an archive staged by DownloadZipWithHandler.

const chunk = await call('DownloadFileChunk', {
  authenticationTicket: ticket,
  DownloadHandler: handler,
  StartOffset: 0,
  ChunkSize: 65536
});

const bytes = Uint8Array.from(atob(chunk.textContent), c => c.charCodeAt(0));

console.log(chunk.getAttribute('filelength'),    // the whole archive
            chunk.getAttribute('chunklength'),   // bytes in this piece
            chunk.getAttribute('chunkCRC32'),    // checksum of this piece
            chunk.getAttribute('lastchunk'));    // "true" when there is no more

The chunk is base64 in the element's own text, so chunklength counts the bytes it decodes to, not the characters that carry them. Advance StartOffset by chunklength each time and stop when lastchunk is "true".

An offset past the end of the archive is 4000, not an empty last chunk - so a loop that steps past the end gets an error rather than a quiet stop. A handler that has been deleted, has expired, or was never a GUID is also 4000.

Notes¶

• The chunk content is base64-encoded in the XML body -" decode it before writing to the output file.

• Use chunklength (not ChunkSize) when advancing StartOffset to correctly handle the shorter final chunk.

• Check chunkCRC32 after decoding each chunk to verify it was not corrupted in transit.

• Stop iterating when lastchunk="true". Do not make a further call with the next offset.

• Passing a string that is not a valid GUID for DownloadHandler returns an error immediately.

• If the handler file has been deleted or expired, an error is returned.

• After all chunks are collected, call DeleteDownloadHandler to free the temporary file on the server.

Related APIs¶

• GetDownloadHandler - Prepare a document for chunked download and obtain the handler GUID

• GetDownloadHandlerByVersion - Prepare a specific document version for chunked download

• DownloadZipWithHandler - Prepare a zip archive of folders and documents for chunked download

• DeleteDownloadHandler - Clean up the download handler after all chunks are retrieved

• UploadFileChunk - Upload counterpart for chunked uploads

Error Codes¶

The errorCode values this operation returns, checked against a running server: