BinaryBuffer Class

The BinaryBuffer class is a utility for managing a block of memory used to send and receive data in a binary protocol, including some methods rather special to DNS. A message can be built inside a new empty buffer object, then sent, or a message can be received into a buffer object which can then be read out.

The buffer is an array of unsigned char, so the each entry is a single byte. The object makes use of the standard header stdint.h (or cstdint in C++). This provides type names for integer values of a specific size. Of particular interest, will be uint8_t, uint16_t and uint32_t, which are unsigned integer values of exactly one, two and four bytes. The uint8_t type is the same as unsigned char.

When BinaryBuffer is used to create a message, the pattern would be something like

Declare a buffer object, like BinaryBuffer buf; .
Use various put methods to add data to the buffer, such as buf.put16(20);, buf.puts("data"); or buf.puthost("some.host.name.edu");.
Use a networking call to transmit the contents, something like send---(...,buf.buf(),buf.loc(),...);.

When receiving, the pattern is

Declare a buffer object, like BinaryBuffer buf; .
Use a networking call to receive the contents, something like int n = recv---(...,buf.buf(),buf.get_bufsize(),...);.
Use various get methods to extract data from the buffer, such as buf.get32();, buf.gets(); or buf.gethost();. These return the values they extract.

Putting and getting pass through the buffer from front to back. The current version has no methods to store or read the data out of order, but you should feel free to add any if you like. The buffer object has a current get/put location which remembers the next byte location (subscript) to read or store.

Notice an asymmetry in the two sides: When you receive network data, you don't know how much you will get. You tell receive the physical size of the buffer with bufsize(). The receive call then returns the number of bytes received. When sending, you use loc() for the size. It returns the get/put location, which is both the location of the next byte to be stored, and also the number of bytes already stored. That way, send will transmit only the data you have inserted.

The interface is as given as follows. Note that all operations which put data into, or get data from, the buffer begin storing or fetching at the current get/put location, and advance that location by the amount of data extracted or stored. There is also a short example client.

BinaryBuffer b;

Create a binary buffer object. The constructor takes no parameters, and the buffer is a fixed size of 1024 bytes. The get/put pointer is at the start of the buffer. (Making it a bit more flexible would not be difficult, but this is fine for the present assignment.)

b.buf()

Returns a pointer to the first byte of data. (This is the traditional way to use the buffer space with the network primitives. You must send it along with bufsize() or loc().) This call sets the get/put pointer to the start of the array.

b.arr()

Returns a reference to the underlying C++ template array of unsigned char which actually holds the data. (Cleansocks can use this instead of get_buf.) This call sets the get/put pointer to the start of the array.

b.bufsize()

Return the physical size of the underlying storage array.

b.loc()

Return the current get/put location, a subscript in the data data array. It is the location of the next byte to read or store, and equivalently the number of bytes which have been read or stored.

b.reset_loc()

Return the get/put pointer to the start. Mainly for reuse of the buffer object.

b.put(d)

b.put8(d)

b.put16(d)

b.put32(d)

Store into the buffer a one, two or four-byte unsigned integer value, d; put and put8 are equivalent. As described above, the data is placed starting at the get/put pointer, which is then advanced. Multibyte values are stored using big-endian byte order, as required by RFC 1035.

b.put_be(d)

This puts a numeric value of whatever type and size d is.

b.puts(s)

This adds a string s to the buffer in the form specified by RFC 1035. It first inserts a byte giving the length of the string, followed by the characters in the string.

b.puthost(h)

This adds a host or domain name h, given as a string, to the buffer using the form specified by RFC 1035. The components are inserted as a sequence of strings followed by a zero byte to terminate entry.

b.get()

b.get8()

b.get16()

b.get32()

Extract and return the next item of the given size, one, two or four bytes; get() is equivalent to get8(). The bytes of multi-byte values are read in big-endian byte order, as expected by RFC 1035.

b.get_be<type>()

This a numeric value of whatever numeric type you specify. (Probably a lot easier to use one of the earlier methods.)

b.gets()

This extracts and returns a string from the buffer. It assumes the string is stored according to RFC 1035, and the get/put location contains the length byte which begins the representation.

b.gethost()

This extracts and returns a host or domain name from the buffer, assuming it is stored in the form specified by RFC 1035. This method understands the compression method described in Section 4.1.4, and will reconstruct and return the complete name, when compressed in the buffer. (Note that puthost never attempts to introduce compression.)

b.peek()

This returns the next byte (unsigned char or uint8_t, which are equivalent) without advancing the get/put pointer.

b.skip(n)

Skip n bytes on an extraction. (Actually just advances the get/put location.)

b.dump(limit, strm)

This is a debugging method that will print out the contents of the buffer to a stream. Both arguments are optional. The stream strm defaults to cout, and the limit to the get/put location. If you want to dump a buffer received from the network, you will probably want to send limit the number of bytes received, which is returned from the receive call.

s.put(p, i)

s.put(a, i)

s.get(p, i)

s.get(a, i)

You probably won't need these. They provide for block transfer of bytes with some other array of unsigned char. All return void. The first and third forms take a pointer p to unsigned char and an integer size i. This is the traditional C way of sending the outside array. The second and fourth form take a C++ template array a of unsigned char. For these, the parameter i is optional, in which case the actual array size is used. Put transfers from the argument array to s, and get transfers from s to the argument array. Each one advances the get/put location by the amount of data.