this avoids littering function definitions in the documentation with
"PROTOBUF_C_API".

identifiers that begin with an underscore are reserved. instead, use a
double underscore in the *middle* of the identifier to indicate that
it's an "internal" identifier.

identifiers that begin with a double underscore are reserved.

this is the unmodified output from "doxygen -l DoxygenLayout.xml".

this is the completely unmodified output output from running
"doxygen -g Doxyfile.in".  (note that this is doxygen 1.8.7.)

customization will come in a subsequent commit so that we have a record
of exactly what was changed from the default values.

exact version coupling between the compiler and the public headers is
too strict because some existing projects (such as collectd,
riemann-c-client, and nmsg) directly embed .pb-c.h files generated by
protoc-c into their exported headers. this would cause unnecessary build
failures in downstream clients of these libraries if a newer version of
the protobuf-c headers is installed.

however, it's still desireable to be able to explicitly declare when
compatibility is broken between the headers and the compiler, so
introduce new variables that allow independently setting the minimum
header version required by the compiler and the minimum compiler version
required by the header.

this follows the protobuf C++ implementation a little bit more closely,
though we don't have an analogous facility for verifying that the header
and *library* are compatible. (this seems like overkill for a C project;
in practice the headers and the library will be from the same version,
especially in downstream distributors like debian where the -dev package
has an exact versioned dependency on the shared library package.)

configure now has a "--enable-code-coverage" option, and if the
lcov/gcov tools are available a code coverage report can be built with
"make check-code-coverage".

this is mostly based on the AX_CODE_COVERAGE / GNOME_CODE_COVERAGE
macro:

    http://savannah.gnu.org/patch/?8451

but i also looked at knot-dns's code coverage implementation:

    https://github.com/CZNIC-Labs/knot/blob/master/m4/code-coverage.m4

and kevin lyda's pull request:

    https://github.com/protobuf-c/protobuf-c/pull/131/files

it's related to the RPC code, and that's been split out into
protobuf-c-rpc now.

this was inadvertently reverted when i was editing e9627054.

this adds a version guard like the protobuf C++ implementation. it
ensures that protoc-c and <protobuf-c.h> are from the exact same version
of protobuf-c.

this replaces the changes in Issue #53 with a slightly different way of
representing / retrieving the version number.

protobuf_c_version() returns the version of the *library* as a string.

protobuf_c_version_number() returns the version of the *library* as an
integer.

PROTOBUF_C_VERSION is the version of the *headers* as a string constant.

PROTOBUF_C_VERSION_NUMBER is the version of the *headers* as an integer.

[edmonds@fsi.io: resolve merge conflicts, add documentation]

rename PROTOBUF_C_FIELD_FLAGS_PACKED to PROTOBUF_C_FIELD_FLAG_PACKED.

rename ProtobufCFieldFlagType to ProtobufCFieldFlag.

wrap some particular long lines.

update documentation.

for clarity, use a "uint32_t" instead of "unsigned" for the 'flags'
field in _ProtobufCFieldDescriptor.

Originally, someone complained about protobuf_c_message_unpack() using
alloca() for the allocation of the temporary bitmap used to detect that
all required fields were present in the unpacked message (Issue #60).
Commit 248eae1d eliminated the use of alloca(), replacing the
variable-length alloca()'d bitmap with a 16 byte stack-allocated bitmap,
treating field numbers mod 128.

Andrei Nigmatulin noted in PR #137 problems with this approach:

    Apparently 248eae1d has introduced a serious problem to protobuf-c
    decoder.

    Originally the function of required_fields_bitmap was to prevent
    decoder from returning incomplete messages. That means, each
    required field in the message either must have a default_value or be
    present in the protobuf stream. The purpose of this behaviour was to
    provide user with 100% complete ProtobufCMessage struct on return
    from protobuf_c_message_unpack(), which does not need to be checked
    for completeness just after. This is exactly how original protobuf
    C++ decoder behaves. The patch 248eae1d broke this functionality by
    hashing bits of required fields instead of storing them separately.

    Consider a protobuf message with 129 fields where the first and the
    last fields set as 'required'. In this case it is possible to trick
    decoder to return incomplete ProtobufCMessage struct with missing
    required fields by providing only one of the two fields in the
    source byte stream. This can be considered as a security issue as
    well because user's code do not expect incomplete messages with
    missing required fields out from protobuf_c_message_unpack(). Such a
    change could introduce undefined behaviour to user programs.

This patch is based on Andrei's fix and restores the exact detection of
missing required fields, but avoids doing a separate allocation for the
required fields bitmap except for messages whose descriptors define a
large number of fields. In the "typical" case where the message
descriptor has <= 128 fields we can just use a 16 byte array allocated
on the stack. (Note that the hash-based approach also used a 16 byte
stack allocated array.)