XPath and XQuery Functions and Operators 4.0

14.6.8 fn:unparsed-binary

Summary

The fn:unparsed-binary function reads an external resource (for example, a file) and returns its contents in binary.

Signature

fn:unparsed-binary(
$source	as xs:string?
) as xs:base64Binary

Properties

This function is deterministic, context-dependent, and focus-independent. It depends on executable base URI.

Rules

The $source argument must be a string in the form of a URI reference, which must contain no fragment identifier, and must identify a resource for which a binary representation is available.

If $source is a relative URI reference, it is resolved relative to the value of the executable base URI^XP property from the dynamic context of the caller. The resulting absolute URI is promoted to an xs:string.

The mapping of URIs to the binary representation of a resource is the mapping defined in the available binary resources^XP component of the dynamic context.

If the $source argument is an empty sequence, the function returns an empty sequence.

The result of the function is an atomic item of type xs:base64Binary containing the binary representation of the resource retrieved using the URI.

Error Conditions

A dynamic error is raised [err:FOUT1170] if the $source argument contains a fragment identifier, or if it cannot be resolved to an absolute URI (for example, because the base-URI property in the static context is absent), or if it cannot be used to retrieve the binary representation of a resource.

Notes

If it is appropriate to use a base URI other than the executable base URI^XP (for example, when resolving a relative URI reference read from a source document) then it is advisable to resolve the relative URI reference using the fn:resolve-uri function before passing it to the fn:unparsed-text function.

There is no essential relationship between the sets of URIs accepted by the function fn:binary-resource and other functions such as fn:doc and fn:unparsed-text (a URI accepted by one may or may not be accepted by the others), and if a URI is accepted by more than one of these functions then there is no essential relationship between the results (different resource representations are permitted by the architecture of the web).There is no essential relationship between the sets of URIs accepted by the function fn:unparsed-binary and other functions such as fn:doc and fn:unparsed-text (a URI accepted by one may or may not be accepted by the others), and if a URI is accepted by more than one of these functions then there is no essential relationship between the results (different resource representations are permitted by the architecture of the web).There is no essential relationship between the sets of URIs accepted by the function fn:binary-resourcefn:unparsed-binary and other functions such as fn:doc and fn:unparsed-text (a URI accepted by one may or may not be accepted by the others), and if a URI is accepted by more than one of these functions then there is no essential relationship between the results (different resource representations are permitted by the architecture of the web).

There are no constraints on the MIME type of the resource.

The fact that the resolution of URIs is defined by a mapping in the dynamic context means that in effect, various aspects of the behavior of this function are implementation-defined. Implementations may provide external configuration options that allow any aspect of the processing to be controlled by the user. In particular:

• The set of URI schemes that the implementation recognizes is implementation-defined. Implementations may allow the mapping of URIs to resources to be configured by the user, using mechanisms such as catalogs or user-written URI handlers.

• The handling of media types is implementation-defined.

• Implementations may provide user options that relax the requirement for the function to return deterministic results.

• Implementations may provide user-defined error handling options that allow processing to continue following an error in retrieving a resource, or in reading its content. When errors have been handled in this way, the function may return a fallback document provided by the error handler.

There is no function (analogous to fn:doc-available or fn:unparsed-text-available) to determine whether a suitable resource is available. In XQuery and XSLT, try/catch constructs are available to catch the error.

The choice of xs:base64Binary rather than xs:hexBinary for the result is arbitrary. The two types have the same value space and are interchangeable for nearly all purposes, the notable exception being conversion to xs:string.

A comprehensive set of functions for manipulating binary data is available in the EXPath binary module: see [EXPath]. In addition, the EXPath file module provides a function file:read-binary with similar functionality to fn:unparsed-binary, the notable differences being (a) that it takes a file name rather than a URI, and (b) that it is defined to be nondeterministic.

Examples

The following XQuery, adapted from an example in the EXPath binary module [EXPath], reads a JPEG image and determines its size in pixels:

declare namespace bin = "http://expath.org/ns/binary"; let $content := fn:binary-resource("image.jpeg") let $int16-at := bin:unpack-unsigned-integer( $content, ?, 2, 'most-significant-first') let $loc := bin:find($content, 0, bin:hex('FFC0')) return { "width": $int16-at($loc + 5), "height": $int16-at($loc + 7) } declare namespace bin = "http://expath.org/ns/binary"; let $content := fn:unparsed-binary("image.jpeg") let $int16-at := bin:unpack-unsigned-integer( $content, ?, 2, 'most-significant-first') let $loc := bin:find($content, 0, bin:hex('FFC0')) return { "width": $int16-at($loc + 5), "height": $int16-at($loc + 7) }

The example assumes that the functions in the EXPath binary module are available.