StringSource

StringSource

Documentation

#include <cryptopp/filters.h>

A StringSource is a source for byte arrays, C-strings and C++ strings.

The StringSource takes a pointer to a BufferedTransformation. Because a pointer is taken, the StringSource owns the attached transformation, and therefore will destroy it. See ownership for more details.

Sources, filters and sinks are discussed at Pipelining. The pipeline article explains the design and shows you how to use them.

Constructors

StringSource (BufferedTransformation *attachment=NULL)

StringSource (const char *zstring,
              bool pumpAll,
              BufferedTransformation *attachment=NULL)

StringSource (const std::string &string,
              bool pumpAll,
              BufferedTransformation *attachment=NULL)

StringSource (const byte *bstring,
              size_t length,
              bool pumpAll,
              BufferedTransformation *attachment=NULL)

zstring is a NULL terminated C-string.

string is a C++ string.

bstring is a byte array.

length is the length of the byte array.

pumpAll is a boolean value indicating if the StringSource should pump all of the data immediately to its attached transformation.

attachment is a BufferedTransformation, such as another filter or sink.

Examples

The following examples demonstrate creation of a StringSource.

StringSource ss( "Hello World" );

string data;
StringSource ss( data );

The following example demonstrates writing a string to a file.

string data;
StringSource ss( data, true /*pumpAll*/, new FileSink( "test.txt" ) );

The following example performs the same operation as above, but without the variable s.

string data;
StringSource ss( data, true /*pumpAll*/, new FileSink( "test.txt" ) );

The following example uses a byte array rather than a string. Note an alternate constructor is used in this case.

const byte arr[] = {0, 2, 4, 6, 8};
StringSource ss( arr, 5, true /*pumpAll*/, new FileSink( "test.txt" ) );

A slightly more complicated example of pipelining is below. Before the string is written to the file, it is HexEncoded.

string s;
StringSource ss( s, true /*pumpAll*/, new HexEncoder( new FileSink( "test.txt" ) ) );

Sometimes the pipeline will be coded over multiple lines to aid in readability. The following is equivalent to the previous.

string s;
StringSource ss( s, true /*pumpAll*/,
    new HexEncoder(
        new FileSink( "test.txt" )
    ) // HexEncoder
); // StringSource

Note that the HexEncoder and FileSink created with new do not require explicit destruction - the StringSource will call delete on the HexEncoder, which in turns calls delete on the FileSink when it (the StringSource) is destroyed.

Missing Data

Its not uncommon to experience Missing Data in a pipeline. A source will send data through a pipeline but have nothing in the sink. This is usually due to the compiler matching the wrong function. For example:

string source = "FF 88 00", destination;
StringSink ss(source,
    new HexDecoder(
        new StringSink(destination)
    ) // HexDecoder
); // StringSink

After the above code executes, destination will likely be empty because the compiler coerces the HexDecoder (the pointer) to a bool (the pumpAll parameter), which leaves the StringSource's attached transformation NULL. The compiler will do so without warning, even with -Wall -Wextra -Wconversion. To resolve the issue, explicitly specify the pumpAll parameter:

string source = "FF 88 00", destination;
StringSink ss(source, true /*pumpAll*/,
    new HexDecoder(
        new StringSink(destination)
    ) // HexDecoder
); // StringSink

Another way data ends up missing is failing to call MessageEnd() when pumping data. For example, the following may not produce expected results:

// The 4-bit nibble will be buffered waiting for another nibble
string source = "FF 88 0", destination;

HexDecoder decoder(new StringSink(destination));
decoder.Put(source.data(), source.size());

// Do something with destination

Be sure to call MessageEnd() when data comes up missing:

string source = "FF 88 0", destination;

HexDecoder decoder(new StringSink(destination));
decoder.Put(source.data(), source.size());
decoder.MessageEnd();

// Do something with destination