balber_berutil

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Terminology
  • Usage
    • Example 1: Reading and Writing Identifier Octets

Purpose

Provide functions to encode and decode simple types in BER format.

Classes

• balber::BerUtil: namespace of utility functions for BER

See also

balber_berencoder, balber_berdecoder

Description

This component provides utility functions for encoding and decoding of primitive BER constructs, such as tag identifier octets, length octets, fundamental C++ types. The encoding and decoding of bsl::string and BDE date/time types is also implemented. For bsl::string_view and bslstl::StringRef types only encoding is supported.

These utility functions operate on bsl::streambuf for buffer management.

More information about BER constructs can be found in the BER specification (X.690). A copy of the specification can be found at the URL:

• http://www.itu.int/ITU-T/studygroups/com17/languages/X.690-0207.pdf

Note that this is a low-level component that only encodes and decodes primitive constructs. Clients should use the balber_berencoder and balber_berdecoder components (which use this component in the implementation) to encode and decode well-formed BER messages.

Terminology

The documentation of this component occasionally uses the following terminology as shorthand:

date-and-time type: A data type provided by BDE for the representation of a date and/or time value. The date-and-time types are: bdlt::Date, bdlt::DateTz, bdlt::Datetime, bdlt::DatetimeTz, bdlt::Time, and bdlt::TimeTz. Note that under this definition, the time-zone-aware types provided by BDE, such as baltzo::LocalDatetime, are not date-and-time types.

date-and-time value: The value associated with an object of a date-and-time type.

Usage

This section illustrates intended use of this component.

Example 1: Reading and Writing Identifier Octets

The following snippets of code illustrate the usage of this component. Due to the low-level nature of this component, an extended usage example is not necessary.

Suppose we wanted to write the identifier octets for a BER tag having the following properties:

  Tag Class:   Context-specific
  Tag Type:    Primitive
  Tag Number:  31

According to the BER specification, this should generate two octets containing the values 0x9F and 0x1F. The following function demonstrates this:

bdlsb::MemOutStreamBuf osb;
 
balber::BerConstants::TagClass tagClass  =
                                  balber::BerConstants::e_CONTEXT_SPECIFIC;
balber::BerConstants::TagType  tagType   =
                                         balber::BerConstants::e_PRIMITIVE;
int                            tagNumber = 31;
 
int retCode = balber::BerUtil::putIdentifierOctets(&osb,
                                                   tagClass,
                                                   tagType,
                                                   tagNumber);
assert(0    == retCode);
assert(2    == osb.length());
assert(0x9F == (unsigned char)osb.data()[0]);
assert(0x1F == (unsigned char)osb.data()[1]);

The next part of the function will read the identifier octets from the stream and verify its contents:

bdlsb::FixedMemInStreamBuf isb(osb.data(), osb.length());
 
balber::BerConstants::TagClass tagClassIn;
balber::BerConstants::TagType  tagTypeIn;
int                            tagNumberIn;
int                            numBytesConsumed = 0;
 
retCode = balber::BerUtil::getIdentifierOctets(&isb,
                                               &tagClassIn,
                                               &tagTypeIn,
                                               &tagNumberIn,
                                               &numBytesConsumed);
assert(0         == retCode);
assert(2         == numBytesConsumed);
assert(tagClass  == tagClassIn);
assert(tagType   == tagTypeIn);
assert(tagNumber == tagNumberIn);