Class: Net::SSH::Buffer

Class | Net::SSH::Buffer
In: | lib/net/ssh/buffer.rb
Parent: | Object

Net::SSH::Buffer is a flexible class for building and parsing binary data packets. It provides a stream-like interface for sequentially reading data items from the buffer, as well as a useful helper method for building binary packets given a signature.

Writing to a buffer always appends to the end, regardless of where the read cursor is. Reading, on the other hand, always begins at the first byte of the buffer and increments the read cursor, with subsequent reads taking up where the last left off.

As a consumer of the Net::SSH library, you will rarely come into contact with these buffer objects directly, but it could happen. Also, if you are ever implementing a protocol on top of SSH (e.g. SFTP), this buffer class can be quite handy.

### Methods

== append available clear! consume! empty? eof? from length new read read! read_bignum read_bool read_buffer read_byte read_int64 read_key read_keyblob read_long read_string read_to remainder_as_buffer reset! to_s write write_bignum write_bool write_byte write_int64 write_key write_long write_string

### Attributes

content | [R] | exposes the raw content of the buffer
position | [RW] | the current position of the pointer in the buffer

### Public Class methods

from(*args)

This is a convenience method for creating and populating a new buffer from a single command. The arguments must be even in length, with the first of each pair of arguments being a symbol naming the type of the data that follows. If the type is :raw, the value is written directly to the hash.

      b = Buffer.from(:byte, 1, :string, "hello", :raw, "\1\2\3\4")
      #-> "\1\0\0\0\5hello\1\2\3\4"

The supported data types are:

- :raw => write the next value verbatim (write)
- :int64 => write an 8-byte integer (write_int64)
- :long => write a 4-byte integer (write_long)
- :byte => write a single byte (write_byte)
- :string => write a 4-byte length followed by character data (write_string)
- :bool => write a single byte, interpreted as a boolean (write_bool)
- :bignum => write an SSH-encoded bignum (write_bignum)
- :key => write an SSH-encoded key value (write_key)

Any of these, except for :raw, accepts an Array argument, to make it easier to write multiple values of the same type in a briefer manner.

new(content="")

Creates a new buffer, initialized to the given content. The position is initialized to the beginning of the buffer.

### Public Instance methods

==(buffer)

Compares the contents of the two buffers, returning `true` only if they are identical in size and content.

append(text)

Appends the given text to the end of the buffer. Does not alter the read position. Returns the buffer object itself.

available()

Returns the number of bytes available to be read (e.g., how many bytes remain between the current position and the end of the buffer).

clear!()

Resets the buffer, making it empty. Also, resets the read position to 0.

consume!(n=position)

Consumes n bytes from the buffer, where n is the current position unless otherwise specified. This is useful for removing data from the buffer that has previously been read, when you are expecting more data to be appended. It helps to keep the size of buffers down when they would otherwise tend to grow without bound.

Returns the buffer object itself.

empty?()

Returns `true` if the buffer contains no data (e.g., it is of zero length).

eof?()

Returns true if the pointer is at the end of the buffer. Subsequent reads will return nil, in this case.

length()

Returns the length of the buffer‘s content.

read(count=nil)

Reads and returns the next `count` bytes from the buffer, starting from the read position. If `count` is `nil`, this will return all remaining text in the buffer. This method will increment the pointer.

read!(count=nil)

Reads (as read) and returns the given number of bytes from the buffer, and then consumes (as consume!) all data up to the new read position.

read_bignum()

Read a bignum (OpenSSL::BN) from the buffer, in SSH2 format. It is essentially just a string, which is reinterpreted to be a bignum in binary format.

read_bool()

Read a single byte and convert it into a boolean, using ‘C’ rules (i.e., zero is false, non-zero is true).

read_buffer()

Reads the next string from the buffer, and returns a new Buffer object that wraps it.

read_byte()

Read and return the next byte in the buffer. Returns nil if called at the end of the buffer.

read_int64()

Return the next 8 bytes as a 64-bit integer (in network byte order). Returns nil if there are less than 8 bytes remaining to be read in the buffer.

read_key()

Read a key from the buffer. The key will start with a string describing its type. The remainder of the key is defined by the type that was read.

read_keyblob(type)

Read a keyblob of the given type from the buffer, and return it as a key. Only RSA and DSA keys are supported.

read_long()

Return the next four bytes as a long integer (in network byte order). Returns nil if there are less than 4 bytes remaining to be read in the buffer.

read_string()

Read and return an SSH2-encoded string. The string starts with a long integer that describes the number of bytes remaining in the string. Returns nil if there are not enough bytes to satisfy the request.

read_to(pattern)

Reads all data up to and including the given pattern, which may be a String, Fixnum, or Regexp and is interpreted exactly as String#index does. Returns nil if nothing matches. Increments the position to point immediately after the pattern, if it does match. Returns all data up to and including the text that matched the pattern.

remainder_as_buffer()

Returns all text from the current pointer to the end of the buffer as a new Net::SSH::Buffer object.

reset!()

Resets the pointer to the start of the buffer. Subsequent reads will begin at position 0.

to_s()

Returns a copy of the buffer‘s content.

write(*data)

Writes the given data literally into the string. Does not alter the read position. Returns the buffer object.

write_bignum(*n)

Writes each argument to the buffer as a bignum (SSH2-style). No checking is done to ensure that the arguments are, in fact, bignums. Does not alter the read position. Returns the buffer object.

write_bool(*b)

Writes each argument to the buffer as a (C-style) boolean, with 1 meaning true, and 0 meaning false. Does not alter the read position. Returns the buffer object.

write_byte(*n)

Writes each argument to the buffer as a byte. Does not alter the read position. Returns the buffer object.

write_int64(*n)

Writes each argument to the buffer as a network-byte-order-encoded 64-bit integer (8 bytes). Does not alter the read position. Returns the buffer object.

write_key(*key)

Writes the given arguments to the buffer as SSH2-encoded keys. Does not alter the read position. Returns the buffer object.

write_long(*n)

Writes each argument to the buffer as a network-byte-order-encoded long (4-byte) integer. Does not alter the read position. Returns the buffer object.

write_string(*text)

Writes each argument to the buffer as an SSH2-encoded string. Each string is prefixed by its length, encoded as a 4-byte long integer. Does not alter the read position. Returns the buffer object.

[Validate]