bdlde_crc32

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Usage
    • Example 1: Basic Usage

Purpose

Provide a mechanism for computing the CRC-32 checksum of a dataset.

Classes

• bdlde::Crc32: stores and updates a CRC-32 checksum

See also

Description

This component implements a mechanism for computing, updating, and streaming a CRC-32 checksum (a cyclic redundancy check comprised of 32 bits). This checksum is a strong and fast technique for determining whether or not a message was received without errors. Note that a CRC-32 checksum does not aid in error correction and is not naively useful in any sort of cryptographic application. Compared to other methods such as MD5 and SHA-256, it is relatively easy to find alternate texts with identical checksum.

Usage

This section illustrates intended use of this component.

Example 1: Basic Usage

The following snippets of code illustrate a typical use of the bdlde::Crc32 class. Each function would typically execute in separate processes or potentially on separate machines. The senderExample function below demonstrates how a message sender can write a message and its CRC-32 checksum to a bdex output stream. Note that Out may be a typedef of any class that implements the bslx::OutStream protocol:

/// Write a message and its CRC-32 checksum to the specified `output`
/// stream.
void senderExample(Out& output)
{
    // prepare a message
    bsl::string message = "This is a test message.";
 
    // generate a checksum for `message`
    bdlde::Crc32 crc(message.data(), message.length());
 
    // write the message to `output`
    output << message;
 
    // write the checksum to `output`
    const int VERSION = 1;
    crc.bdexStreamOut(output, VERSION);
}

The receiverExample function below illustrates how a message receiver can read a message and its CRC-32 checksum from a bdex input stream, then perform a local CRC-32 computation to verify that the message was received intact. Note that In may be a typedef of any class that implements the bslx::InStream protocol:

/// Read a message and its CRC-32 checksum from the specified `input`
/// stream, and verify the integrity of the message.
void receiverExample(In& input)
{
    // read the message from `input`
    bsl::string message;
    input >> message;
 
    // read the checksum from `input`
    bdlde::Crc32 crc;
    const int VERSION = 1;
    crc.bdexStreamIn(input, VERSION);
 
    // locally compute the checksum of the received `message`
    bdlde::Crc32 crcLocal;
    crcLocal.update(message.data(), message.length());
 
    // verify that the received and locally-computed checksums match
    assert(crcLocal == crc);
}