This proposal provides an API for XPath 2.0 to handle binary data. It defines extension functions to read binary files, perform basic binary operations on the data in memory, as well as a new serialization method. It has been designed to be compatible with XQuery 1.0 and XSLT 2.0, as well as any other XPath 2.0 usage.
The module defined by this document defines several functions and a serialization
method, all contained in the namespace http://expath.org/ns/binary. In
this document, the bin prefix, when used, is bound to this namespace
URI.
Error codes are defined in the namespace http://expath.org/ns/error. In
this document, the err prefix, when used, is bound to this namespace
URI.
Development of this specification was driven strictly by requirements which XML developer regularly faces.
Some typical use cases:
Getting dimensions of an image file.
Extracting image metadata.
Processing images embeded and base64 encoded inside SOAP message.
Processing legacy text file which uses several different encodings in different places.
The bin:unparsed-binary function reads an external resource (for example, an image
file) and returns a binary data of the resource.
bin:unparsed-binary($href as xs:string?) as xs:hexBinary?The $href 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 string representation is available. If the URI is a
relative URI reference, then it is resolved relative to the
Static Base URI property from the static context.
If the value of the $href argument is an empty sequence, the function
returns an empty sequence.
The result of the function is a binary value of the resource retrieved using the URI.
Converting external images in HTML document into internal data: resources:
The bin:binary-subsequence functions returns specified part of binary data.
bin:binary-subsequence($in as xs:hexBinary, $offset as xs:integer, $size as xs:integer) as xs:hexBinaryReturns part of original binary data starting at $offset. Size of
returned data is $size octets.
The $offset is zero based.
The value of $offset argument MUST be non-negative integer.
It is dynamic error if $offset + $size is larger then size of binary data passed in $in argument.
Testing whether $data variable contains content of PDF file:
25504446 is magic number for PDF files, it is US-ASCII encoded value for %PDF.
The bin:binary-length functions returns size of binary data.
bin:binary-length($in as xs:hexBinary) as xs:integerReturns size of binary data in octets.
Returns a binary data created by concatenating the binary data items in a sequence.
bin:binary-join($in as xs:hexBinary*) as xs:hexBinaryThe function returns an xs:hexBinary created by concatenating the items in the
sequence $in, in order.
If the value of $in is the empty sequence, the function returns the
zero-length binary data.
Returns binary data as a sequence of octets.
bin:binary-to-octets($in as xs:hexBinary) as xs:integer*If $in is zero length binary data then empty sequence is returned.
Octets are returned as integers from 0 to 255.
Converts sequence of octets into binary data.
bin:octets-to-binary($in as xs:integer*) as xs:hexBinaryOctets are integers from 0 to 255.
Decodes binary data as a string in a given encoding.
bin:decode-string($in as xs:hexBinary, $encoding as xs:string) as xs:stringThe $encoding argument is the name of an encoding. The values
for this attribute follow the same rules as for the encoding attribute in
an XML declaration. The only values which every implementation is REQUIRED to recognize are
utf-8 and utf-16.
Decodes chunk of binary data at a specified offset as a string in a given encoding.
bin:unpack-string($in as xs:hexBinary, $offset as xs:integer, $size as xs:integer, $encoding as xs:string) as xs:stringIf $size is greater then 0 this function is identical to calling bin:decode-string(bin:binary-subsequence($in, $offset, $size), $encoding).
If $size is zero then all non-zero octets starting at $offset until first zero octet are extracted and then decoding is applied. This way zero-terminated
strings can be easily decoded.
The $encoding argument is the name of an encoding. The values
for this attribute follow the same rules as for the encoding attribute in
an XML declaration. The only values which every implementation is REQUIRED to recognize are
utf-8 and utf-16.
Encodes string into binary data using a given encoding.
bin:encode-string($in as xs:string, $encoding as xs:string) as xs:hexBinaryThe $encoding argument is the name of an encoding. The values
for this attribute follow the same rules as for the encoding attribute in
an XML declaration. The only values which every implementation is REQUIRED to recognize are
utf-8 and utf-16.
Extract double value stored at the particular offset in binary data.
bin:unpack-double($in as xs:hexBinary, $offset as xs:integer) as xs:doublebin:unpack-double($in as xs:hexBinary, $offset as xs:integer, $bigendian as xs:boolean) as xs:doubleLittle endian number representation is assumed unless $bigendian parameter is specified and has true() value.
The $offset is zero based.
Extract float value stored at the particular offset in binary data.
bin:unpack-float($in as xs:hexBinary, $offset as xs:integer) as xs:floatbin:unpack-float($in as xs:hexBinary, $offset as xs:integer, $bigendian as xs:boolean) as xs:floatLittle endian number representation is assumed unless $bigendian parameter is specified and has true() value.
The $offset is zero based.
Extract long (64-bit signed integer) value stored at the particular offset in binary data.
bin:unpack-long($in as xs:hexBinary, $offset as xs:integer) as xs:longbin:unpack-long($in as xs:hexBinary, $offset as xs:integer, $bigendian as xs:boolean) as xs:longLittle endian number representation is assumed unless $bigendian parameter is specified and has true() value.
The $offset is zero based.
Extract unsignedLong (64-bit unsigned integer) value stored at the particular offset in binary data.
bin:unpack-unsignedLong($in as xs:hexBinary, $offset as xs:integer) as xs:unsignedLongbin:unpack-unsignedLong($in as xs:hexBinary, $offset as xs:integer, $bigendian as xs:boolean) as xs:unsignedLongLittle endian number representation is assumed unless $bigendian parameter is specified and has true() value.
The $offset is zero based.
Extract int (32-bit signed integer) value stored at the particular offset in binary data.
bin:unpack-int($in as xs:hexBinary, $offset as xs:integer) as xs:intbin:unpack-int($in as xs:hexBinary, $offset as xs:integer, $bigendian as xs:boolean) as xs:intLittle endian number representation is assumed unless $bigendian parameter is specified and has true() value.
The $offset is zero based.
Extract unsignedInt (32-bit unsigned integer) value stored at the particular offset in binary data.
bin:unpack-unsignedInt($in as xs:hexBinary, $offset as xs:integer) as xs:unsignedIntbin:unpack-unsignedInt($in as xs:hexBinary, $offset as xs:integer, $bigendian as xs:boolean) as xs:unsignedIntLittle endian number representation is assumed unless $bigendian parameter is specified and has true() value.
The $offset is zero based.
Extract short (16-bit signed integer) value stored at the particular offset in binary data.
bin:unpack-short($in as xs:hexBinary, $offset as xs:integer) as xs:shortbin:unpack-short($in as xs:hexBinary, $offset as xs:integer, $bigendian as xs:boolean) as xs:shortLittle endian number representation is assumed unless $bigendian parameter is specified and has true() value.
The $offset is zero based.
Extract unsignedShort (16-bit unsigned integer) value stored at the particular offset in binary data.
bin:unpack-unsignedShort($in as xs:hexBinary, $offset as xs:integer) as xs:unsignedShortbin:unpack-unsignedShort($in as xs:hexBinary, $offset as xs:integer, $bigendian as xs:boolean) as xs:unsignedShortLittle endian number representation is assumed unless $bigendian parameter is specified and has true() value.
The $offset is zero based.
Extract byte (8-bit signed integer) value stored at the particular offset in binary data.
bin:unpack-byte($in as xs:hexBinary, $offset as xs:integer) as xs:byteThe $offset is zero based.
Extract unsignedByte (8-bit unsigned integer) value stored at the particular offset in binary data.
bin:unpack-unsignedByte($in as xs:hexBinary, $offset as xs:integer) as xs:unsignedByteThe $offset is zero based.
Returns binary representation of a double value.
bin:pack-double($in as xs:double) as xs:hexBinarybin:pack-double($in as xs:double, $bigendian as xs:boolean) as xs:hexBinaryLittle endian number representation is assumed unless $bigendian parameter is specified and has true() value.
Returns binary representation of a float value.
bin:pack-float($in as xs:float) as xs:hexBinarybin:pack-float($in as xs:float, $bigendian as xs:boolean) as xs:hexBinaryLittle endian number representation is assumed unless $bigendian parameter is specified and has true() value.
Returns binary representation of a long value.
bin:pack-long($in as xs:long) as xs:hexBinarybin:pack-long($in as xs:long, $bigendian as xs:boolean) as xs:hexBinaryLittle endian number representation is assumed unless $bigendian parameter is specified and has true() value.
Returns binary representation of an unsignedLong (64-bit unsigned integer) value.
bin:pack-unsignedLong($in as xs:unsignedLong) as xs:hexBinarybin:pack-unsignedLong($in as xs:unsignedLong, $bigendian as xs:boolean) as xs:hexBinaryLittle endian number representation is assumed unless $bigendian parameter is specified and has true() value.
Returns binary representation of an int (32-bit signed integer) value.
bin:pack-int($in as xs:int) as xs:hexBinarybin:pack-int($in as xs:int, $bigendian as xs:boolean) as xs:hexBinaryLittle endian number representation is assumed unless $bigendian parameter is specified and has true() value.
Returns binary representation of an unsignedInt (32-bit unsigned integer) value.
bin:pack-unsignedInt($in as xs:unsignedInt) as xs:hexBinarybin:pack-unsignedInt($in as xs:unsignedInt, $bigendian as xs:boolean) as xs:hexBinaryLittle endian number representation is assumed unless $bigendian parameter is specified and has true() value.
Returns binary representation of a short (16-bit signed integer) value.
bin:pack-short($in as xs:short) as xs:hexBinarybin:pack-short($in as xs:short, $bigendian as xs:boolean) as xs:hexBinaryLittle endian number representation is assumed unless $bigendian parameter is specified and has true() value.
Returns binary representation of an unsignedShort (16-bit unsigned integer) value.
bin:pack-unsignedShort($in as xs:unsignedShort) as xs:hexBinarybin:pack-unsignedShort($in as xs:unsignedShort, $bigendian as xs:boolean) as xs:hexBinaryLittle endian number representation is assumed unless $bigendian parameter is specified and has true() value.
Returns binary representation of a byte (8-bit signed integer) value.
bin:pack-byte($in as xs:byte) as xs:hexBinaryReturns binary representation of an unsignedByte (8-bit unsigned integer) value.
bin:pack-unsignedByte($in as xs:unsignedByte) as xs:hexBinaryReturns "bitwise or" applied on arguments.
bin:binary-or($a as xs:hexBinary, $b as xs:hexBinary) as xs:hexBinaryReturns "bitwise or" applied on $a and $b.
If $a and $b do not have same length
then shorter is padded with zero octets to match size of a longer argument.
Returns "bitwise xor" applied on arguments.
bin:binary-xor($a as xs:hexBinary, $b as xs:hexBinary) as xs:hexBinaryReturns "bitwise exclusive or" applied on $a and $b.
If $a and $b do not have same length
then shorter is padded with zero octets to match size of a longer argument.
Returns "bitwise and" applied on arguments.
bin:binary-and($a as xs:hexBinary, $b as xs:hexBinary) as xs:hexBinaryReturns "bitwise and" applied on $a and $b.
If $a and $b do not have same length
then shorter is padded with zero octets to match size of a longer argument.
Returns "bitwise not" of an argument.
bin:binary-and($in as xs:hexBinary) as xs:hexBinaryReturns "bitwise not" applied on $in argument.
Shift bits in binary data.
bin:binary-shift($in as xs:hexBinary, $by as xs:integer) as xs:hexBinaryIf $by is positive then bits are shifted $by times to the left.
If $by is negative then bits are shifted -$by times to the right.
If $by is zero result is identical to $in argument.
Result has always the same size as $in argument.
Shift is logical, zeros are placed into discarded bits.
New serialization method bin:binary is defined.
It can serialize sequence containing only items of type xs:hexBinary
or xs:base64Binary. Such sequence is turned into one block of binary data
using bin:binary-join and written out to the specified location.
Joining several blobs of data into a single file:
Template for extracting HTML images represented as data: URI scheme into separate external image files:
Proper error codes and conditions will be defined in the next version of this draft.