Sockets

 read binary data from a network connection

Parameters

 a - rtable with hardware datatype sid - valid open socket ID

Description

 • Because Maple strings are incapable of encoding binary data (containing null bytes), an interface different from Sockets[Read] is required for applications that need to be able to transmit such data. This is achieved by using procedure ReadBinary.
 • The first argument a to procedure ReadBinary must be a hardware rtable; that is, one whose datatype is one of the following:

 integer[ 1 ] integer[ 2 ] integer[ 4 ] integer[ 8 ] float[ 4 ] float[ 8 ]

 The rtable a should not use any indexing functions and the storage parameter should not be set to anything other than rectangular.
 If the datatype is anything other than integer[1], then the data to be read is treated as structured according to the indicated datatype and each record'' is converted to the host byte order. For example, passing an rtable whose datatype is float[4] causes each four-byte float to be converted from Network Byte Order to Host Byte Order.
 • ReadBinary accepts a socket ID sid as its second argument. Parameter sid indicates the network connection from which to read the data.
 • ReadBinary attempts to read as much data from the socket connection as it can, up to the total amount of space available in the rtable a. The number of bytes actually read is returned.
 Note: There may be more data available on the socket than can be accommodated in the rtable passed to ReadBinary. Once the rtable has been filled, ReadBinary returns, leaving any unread data on the socket for subsequent calls to consume.
 It is also possible that there is insufficient data available on the socket to fill rtable a.

Examples

 > $\mathrm{with}\left(\mathrm{Sockets}\right):$
 > $s≔\mathrm{Open}\left("localhost","echo"\right)$
 ${0}$ (1)
 > $\mathrm{Write}\left(s,"Hello"\right)$
 ${5}$ (2)
 > $a≔\mathrm{Array}\left(1..10,'\mathrm{datatype}'='\mathrm{integer}'\left[1\right]\right)$
 ${a}{≔}\left[\begin{array}{cccccccccc}{0}& {0}& {0}& {0}& {0}& {0}& {0}& {0}& {0}& {0}\end{array}\right]$ (3)
 > $\mathrm{ReadBinary}\left(a,s\right)$
 ${5}$ (4)
 > $a$
 $\left[\begin{array}{cccccccccc}{72}& {101}& {108}& {108}& {111}& {0}& {0}& {0}& {0}& {0}\end{array}\right]$ (5)
 > $\mathrm{convert}\left(\mathrm{convert}\left(a,'\mathrm{list}'\right),'\mathrm{bytes}'\right)$
 ${"Hello"}$ (6)
 > $\mathrm{Close}\left(s\right)$
 ${\mathrm{true}}$ (7)

The time service (RFC 868) delivers the current time (measured as the number of seconds since 00:00 (midnight) 01 January 1900) as a 32-bit integer in Network Byte Order.

 > $s≔\mathrm{Open}\left("mantis","time"\right)$
 ${0}$ (8)
 > $a≔\mathrm{Array}\left(1..4,'\mathrm{datatype}'='\mathrm{integer}'\left[4\right]\right)$
 ${a}{≔}\left[\begin{array}{cccc}{0}& {0}& {0}& {0}\end{array}\right]$ (9)
 > $\mathrm{ReadBinary}\left(a,s\right)$
 ${4}$ (10)
 > $a\left[1\right]$
 ${391705059}$ (11)
 > $\mathrm{Close}\left(s\right)$
 ${\mathrm{true}}$ (12)