Package byteblock

The byteblock package defines classes used to manage rectangular "blocks" of bytes and "windows" into such blocks.

See:
Description

Class Summary

ByteBlock	Defines a rectangular block of bytes; used as the base block for byte block windows.
ByteBlockMaskedWindow	Extends ByteBlockRectangularWindow to include a mask specifying only those bits in each byte which will be read or written (corresponding to the positions of 1's in the mask byte).
ByteBlockMultiWindow	Groups a list of byte block windows into a single logical window.
ByteBlockRectangularWindow	A rectangular window into a byte block.
ByteBlockWindow	Abstract base class for "windows" into byte blocks, which are used to read and write data of various types.

Package byteblock Description

The byteblock package defines classes used to manage rectangular "blocks" of bytes and "windows" into such blocks. Typically, an underlying ByteBlock is created with a specified number of rows and columns (in the AirPort configurator, the underlying block of 17 k bytes is represented as a block with 16*68 rows and 16 columns). Then various ByteBlockWindow subclasses are created which expose specified regions of the byte block for reading or writing specific pieces of data.

The most common subclass is the ByteBlockRectangularWindow, which defines a window with a specified number of rows and columns, starting at a specified position (row and column) in the base block, which "wraps" if necessary onto subsequent rows. For example, using the AirPort base block, a rectangular window which starts at row 0, column 8, of the base block, and 1 row and 32 columns, will wrap onto rows 1 and 2, ending with the byte in column 7 of row 2. These rectangular windows also accomodate some of the more unusual field organizations in the AirPort, such as the 2-column-wide ("vertically oriented") network name field, as well as simple single-byte (1 row by 1 column) indicator or count fields.

A subclass of ByteBlockRectangularWindow is ByteBlockMaskedWindow, which includes a mask applied to each byte before reading or writing a value (only the bits in each byte corresponding to 1's in the mask are read or written). These masked windows are useful when a byte is "shared" by two indicators - for example, the high-order 4 bits might indicate the state of one parameter, while the low-order bits indicate the state of another.

Finally, the ByteBlockMultiWindow subclass of ByteBlockWindow permits a field to be comprised of multiple windows which are viewed as a single contiguous field for reading and writing. For example, the field for the DNS server IP address in the AirPort memory block consists of the first two bytes of the address in one location and the the other two in another location, with other data located in between. To accomodate this, a ByteBlockMultiWindow can be created, and two 2-byte ByteBlockRectangularWindows created at the appropriate locations and then added to the ByteBlockMultiWindow. Note that the order in which information is written to the windows comprising the multi-window is determined by the order in which they are added to the multi-window. Also note that the comprising windows need not be disjoint, but that the later-added windows will overwrite overlapping entries in the earlier-added windows when a value is written.

The basic operations for any window are getBytes(), clearBytes(), and setBytes(); note that writing is truncated at the window edge if the byte array being written is larger than the window.