GetDownloadHandlerByVersion API¶

Stages a specific version of a document as a temporary server-side file and returns a download handler GUID along with file metadata and the negotiated chunk size. This is the version-aware counterpart to GetDownloadHandler, which always stages the latest version. Use DownloadFileChunk to retrieve the file data in sequential chunks, then DeleteDownloadHandler to clean up the temporary file when done.

Endpoint¶

/srv.asmx/GetDownloadHandlerByVersion

Methods¶

• GET /srv.asmx/GetDownloadHandlerByVersion?AuthenticationTicket=...&Path=...&PreferedChunkSize=...&VersionNumber=...

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

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

Parameters¶

Version Number Format¶

infoRouter packs a major, a minor and a revision into one integer as major * 1000000 + minor * 1000 + revision, so the number is not an ordinal:

Read the numbers a document actually carries from GetDocumentVersions rather than computing them: successive check-ins normally bump the revision, so the second version of a document is 1000001, not 2000000.

Always use the Number attribute from GetDocumentVersions to obtain the correct value -" do not multiply the sequential version number yourself, as the internal numbering may not always follow this simple pattern.

Response¶

Success Response¶

The server stages the specified document version, creates a temporary handler, and returns file metadata along with the handler GUID.

<response success="true"

          Size="102400"

          ContentType="application/pdf"

          ModificationDate="2024-03-10"

          VersionNumber="1000000"

          AlterDocumentName="Q1-Report.pdf"

          RenderedContent="false"

          CRC32="a3f1c29d"

          ChunkSize="1048576"

          downloadhandler="7f3a1b2c-d4e5-6789-abcd-ef0123456789" />

Response Attributes¶

Error Response¶

<response success="false" error="[901] Session expired or Invalid ticket" />

Required Permissions¶

The calling user must have at least read access to the document. Offline (archived) documents cannot be downloaded and return an error.

Chunked Download Workflow¶

1. GetDocumentVersions              -'  list versions, obtain VersionNumber for the desired version

2. GetDownloadHandlerByVersion      -'  stage that version, obtain downloadhandler GUID + ChunkSize + Size

3. DownloadFileChunk (--N)           -'  download chunks sequentially until lastchunk="true"

4. DeleteDownloadHandler            -'  clean up the temporary staged file on the server

Chunk iteration pattern:

chunkSize   = response/@ChunkSize

totalSize   = response/@Size

handler     = response/@downloadhandler

offset      = 0

loop:

    GET /srv.asmx/DownloadFileChunk

        ?DownloadHandler={handler}

        &StartOffset={offset}

        &ChunkSize={chunkSize}

    append base64-decoded chunk bytes to output file

    offset += chunk/@chunklength

    if chunk/@lastchunk == "true": break

GET /srv.asmx/DeleteDownloadHandler?DownloadHandler={handler}

Always use chunklength from the DownloadFileChunk response (not the requested ChunkSize) when advancing StartOffset, because the final chunk may be smaller.

Example¶

GET Request¶

GET /srv.asmx/GetDownloadHandlerByVersion

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

  &Path=/Finance/Reports/Q1-Report.pdf

  &PreferedChunkSize=1048576

  &VersionNumber=1000000

HTTP/1.1

POST Request¶

POST /srv.asmx/GetDownloadHandlerByVersion HTTP/1.1

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

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

&Path=/Finance/Reports/Q1-Report.pdf

&PreferedChunkSize=1048576

&VersionNumber=1000000

SOAP Request¶

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

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

  <soap:Body>

    <tns:GetDownloadHandlerByVersion>

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

      <tns:Path>/Finance/Reports/Q1-Report.pdf</tns:Path>

      <tns:PreferedChunkSize>1048576</tns:PreferedChunkSize>

      <tns:VersionNumber>1000000</tns:VersionNumber>

    </tns:GetDownloadHandlerByVersion>

  </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;
}

Describes one named version and opens a chunked read of it, for DownloadFileChunk.

const opened = await call('GetDownloadHandlerByVersion', {
  authenticationTicket: ticket,
  Path: '/Finance/Reports/Q1.pdf',
  PreferedChunkSize: 65536,
  VersionNumber: 1000000
});

const handler = opened.getAttribute('downloadhandler');
const chunkSize = Number(opened.getAttribute('ChunkSize'));   // use this, not the number you sent

try {
  // ... read with DownloadFileChunk ...
} finally {
  await call('DeleteDownloadHandler', { authenticationTicket: ticket, DownloadHandler: handler });
}

PreferedChunkSize is a suggestion: the server clamps it and reports what it chose as ChunkSize.

Four operations, two decisions¶

All four answer the same attributes - Size, ContentType, ModificationDate, VersionNumber, AlterDocumentName and CRC32 - and the two that open a read add ChunkSize and downloadhandler. VersionNumber is echoed back exactly as it was asked for, so a 0 stays 0 rather than resolving to the number of the published version.

Notes¶

• VersionNumber is the packed major * 1000000 + minor * 1000 + revision, not an ordinal. Use the Number attribute from GetDocumentVersions rather than computing it. Values between 1 and 999,999 are explicitly rejected and will return an error.

• Passing VersionNumber=0 stages the latest version, which is equivalent to calling GetDownloadHandler.

• The PreferedChunkSize value is clamped server-side: values below 262,144 bytes (256 KB) are raised to 262,144; values above 33,554,432 bytes (32 MB) are lowered to 33,554,432. Always read the actual ChunkSize from the response.

• The staged file is stored as a temporary server-side file. Always call DeleteDownloadHandler after completing (or abandoning) a download to free disk space.

• Both full infoRouter paths and short document ID paths (~D{id} or ~D{id}.ext) are accepted for the Path parameter.

• Offline (archived) documents cannot be staged and will return an error.

• The handler is tied to the authenticated session. Do not share handler GUIDs across different user sessions.

• To download a version without chunking use DownloadDocumentVersion (returns raw bytes directly).

Related APIs¶

• GetDocumentVersions - Get the version list for a document to obtain valid VersionNumber values

• GetDownloadHandler - Create a download handler for the latest version of a document

• DownloadFileChunk - Download a single chunk of a staged file using a handler GUID

• DeleteDownloadHandler - Delete a download handler and discard the staged temporary file

• GetDownloadInfo - Get download metadata without staging a handler

• DownloadDocumentVersion - Download a specific version as a raw byte array (no chunking)

Error Codes¶

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

A call with no ticket signs in as the anonymous user, so a document in a library flagged as anonymous can be read without authenticating.