blokutil.h

伯克利做的SFTP安全文件传输协议

// blokutil.h
// some additional utilities for DataBlock, including conversions
//   to/from Integer class
// copyright SafeTP Development Group, Inc., 2000  Terms of use are as specified in license.txt

#ifndef __BLOKUTIL_H
#define __BLOKUTIL_H

#include "datablok.h"    // DataBlock
#include "integer.h"     // Integer, RandomNumberGenerator
#include "str.h"         // string
#include "socketd.h"     // IPAddress

class RandomNumberGenerator;


// NOTE: Everything in blokutil assumes responsibility for throwing
//       xFormat (as opposed to x_assert) when reading a data block
//       that is either corrupted or too small.


// functional constructors
DataBlock Left(int bytes, DataBlock const &block);
DataBlock concat(DataBlock const &b1, DataBlock const &b2);
DataBlock Right(int bytes, DataBlock const &src);

DataBlock randomDataBlock(RandomNumberGenerator &rng, int bytes);

// improve readability a little
inline DataBlock operator|| (DataBlock const &b1, DataBlock const &b2)
{
  return concat(b1, b2);
}


// conversion between Integer and DataBlock; this conversion simply
// copies the bits back and forth, where the DataBlock is stored in
// big-endian order (first byte is most significant)
// NOTE: only non-negative values can be encoded with these functions!
Integer dataBlock2Integer(DataBlock const &block);
DataBlock integer2DataBlock(Integer const &value);

// version that always has a specific size; an exception is thrown if
// the size is too small to accomodate 'value'
DataBlock integer2DataBlock(Integer const &value, int bytes);

// # of bytes used to store an integer by integer2DataBlock
int sizeAsDataBlock(Integer const &value);


// DataBlock as stream:  Though inefficient, it is convenient to treat
// a DataBlock as a sink to which any amount of data can be appended,
// and similarly as a source for reading that data.  This is generally
// only used in places where some other slow operation will dominate
// performance.
//
// These functions are designed to be faster when the stream already has
// enough space allocated, but correct when it doesn't.
//
// Note that data is read in the *reverse* order from which it is
// written.  This is because DataBlock supports modifying the end of
// the block more efficiently than modifying the beginnning.
//
// Summary of terminology:
//   append - append the value to the DataBlock
//   remove - remove and return the value from the end of the DataBlock

// generic blocks
void appendBlock(DataBlock &stream, DataBlock const &block);
DataBlock removeBlock(DataBlock &stream, int bytes);

// Network Byte Order (big-endian) 32-bit signed quantities
void appendNBO32(DataBlock &stream, long value);
long removeNBO32(DataBlock &stream);

// Integers
void appendInteger(DataBlock &stream, Integer const &value);
Integer removeInteger(DataBlock &stream);

// strings
void appendString(DataBlock &stream, char const *str);
string removeString(DataBlock &stream);

// single bytes
void appendByte(DataBlock &stream, byte b);
byte removeByte(DataBlock &stream);

// IP addresses
void appendIPAddress(DataBlock &stream, IPAddress addr);
IPAddress removeIPAddress(DataBlock &stream);

#endif // __BLOKUTIL_H