Component balber_berutil [Package balber]

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

Namespaces
namespace	balber

---

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:

Component balber_berencoder, Component 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.

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);