DataBuffer object

From StealthBot Wiki
Jump to: navigation, search

The DataBuffer object allows easy manipulation of binary data (byte arrays). It is typically used for creating and parsing network packets.

This object makes heavy use of the Windows CopyMemory function. Byte order is little-endian.

How to use

To create a new empty DataBuffer:

Set buffer = DataBufferEx()

To place data in the buffer:

strData = "this is a string"
buffer.Data = strData

Properties

List of properties

Data property

Gets or sets the buffer's underlying data, as a string.

Length property

Returns the number of bytes in the buffer.

Position property

Gets or sets the current read position in the buffer (0-based).


Read Functions

Read functions return values converted from the buffer at the current position. If the *peek* parameter is not set to True then the read position will be advanced by the size of the value read.

List of read functions

GetByte function

Returns a single byte from the array.

GetByteArr function

Reads *length* bytes of the array into the (ByRef) *data* parameter. This is technically not a function and does not return a value.

GetWord function

Returns a 16-bit (2-byte) value from the buffer. This is the equivalent of VB6's *Integer* type.

GetDWord function

Returns a 32-bit (4-byte) value from the buffer. This is the equivalent of VB6's *Long* type.

GetBool function

Returns FALSE if the next 32-bit value equals 0, or TRUE otherwise. Despite a Boolean value only requiring a single bit, most of Blizzard's classic protocols use 4 bytes for these values.

GetFileTime function

Returns a 64-bit (8-byte) value from the buffer. This is the equivalent of VB6's *Date* type.

GetString function

Returns a string starting at the current position and going until the next NULL byte. The string will be decoded using the encoding specified in the optional *encoding* parameter (default ANSI). This is the opposite of the InsertNTString() method.

Supported encodings:

  • ANSI: 1
  • UTF8: 2
  • UTF16: 3

These encodings are supported for any function or method with an encoding parameter.

GetStringArr function

Returns an array of null-terminated strings starting at the current position and going until a null-string (0 length, or double NULL byte) is found.

GetRaw function

Returns a "binary" string of *length* starting at the current position. This string is not encoded and does not have a terminator. If no *length* is given, it will read until the end of the buffer. This is the opposite of the InsertNonNTString() method.


Write Methods

Write methods insert the binary representation of values into the buffer as an array of bytes. Data will always be appended to the end of the buffer and not the current position.

List of write methods

InsertByte method

Inserts a single byte onto the end of the buffer.

InsertByteArr method

Inserts an array of bytes onto the end of the buffer.

InsertWord method

Inserts a 16-bit (2-byte) value onto the end of the buffer. This is the equivalent of VB6's *Integer* type.

InsertDWord method

Inserts a 32-bit (4-byte) value onto the end of the buffer. This is the equivalent of VB6's *Long* type.

InsertBool method

Inserts a 1 if *data* is TRUE otherwise a 0. This will insert 4 bytes (the value followed by 3 null bytes). Despite a Boolean value only requiring a single bit, most of Blizzard's classic protocols use 4 bytes for these values.

InsertNonNTString method

Inserts a raw "binary" string onto the end of the buffer, without a terminator. This is the opposite of the GetRaw() function.

InsertNTString method

Inserts a null-terminated string onto the end of the buffer. The string will be encoded using the encoding specified in the optional *encoding* parameter (default ANSI). This is the opposite of the GetString() function.

Supported encodings:

  • ANSI: 1
  • UTF8: 2
  • UTF16: 3

These encodings are supported for any function or method with an encoding parameter.


Helper Functions

The DataBuffer object also contains several helper functions.

List of helper functions

SetDataAsByteArr method

Sets the underlying data of the buffer directly to a byte array. This is essentially the same as setting the Data property but without the string-to-byte conversion, because the value is already bytes.

GetDataAsByteArr function

Returns the underlying buffer as a byte array.

Clear method

Clears all data from the buffer and resets the position.

DebugOutput function

Returns the data as a string in a human-readable, debug-friendly format. Optional parameters specify where to start the output and how many bytes to show. 16 bytes are displayed on each line. The first number is the start byte position (0-based). The second set of numbers is the binary representation of the data. After that is a string representation of any printable characters. Non-printable characters are shown as periods (.).

Example output:

0000: FF 07 14 00 36 38 58 49  4E 42 32 57 4F 00 00 00  |....68XI NB2WO...|

SendData function

Writes the data in the buffer to a socket's network stream.

The optional *PacketID* and *ServerType* parameters are used for categorizing the transmission in packet logs. If the optional *HeaderType* parameter is given, the specified packet header arrangement will be prepended to the data before it is sent.

Supported server types:

  • stGEN = 0 (Default value, generic transmission)
  • stBNCS = 1
  • stBNLS = 2
  • stMCP = 3
  • stBNFTP = 4
  • stPROXY = 5

Supported header types:

  • phtNONE = 0 (Default value, no packet header)
  • phtBNCS = 4
  • phtMCP = 3

phtBNCS is a 4-byte header consisting of a start byte (&HFF), the packet ID, and the length of the entire packet including the header as a 16-bit value. phtMCP is a 3-byte header consisting of the packet's length as a 16-bit value and the packet ID.

Returns TRUE if the packet was sent.

SendPacket function

Sends the data to Battle.net through the bot's internal socket.

When using this method the packet header will be applied automatically. You should specify the desired packet ID as the parameter to this function.

SendPacketMCP function

Sends the data to the Diablo 2 realm server, automatically applying the header. You should specify the desired packet ID as the parameter to this function.

vLSendPacket function

Sends the data to the BNLS server, if connected. The 'vL' is for the name of the group that originally designed the BNLS system. Packet ID should be specified as the parameter to this function, and the header will be applied automatically.

GetDataAndAppend method

Reads *length* bytes of data from the given socket and appends them to the buffer.

HandleRecvData function

Runs a received packet through the standard packet handling mechanism, raising the relevant PacketReceived events and adding it to the packet log.

FindByte function

Finds the absolute position in the buffer of the next byte equal to *value* starting at the current read position.

IsFullPacket function

Returns TRUE if a full packet's worth of data is available in the buffer. This is based on the header's length value.

GetPacketLength

Returns the length specified in the current packet's header. This isn't necessarily the same as the length of data in the buffer.

TakePacket

Returns and removes a packet from the buffer.