QPack for the C programming language (libqpack)

Fast and efficient data serializer for the C/C++ programming language. QPack is originally created for SiriDB but is now used by a lot of other projects too.

Installation
Usage
- Packer
- Unpacker
API

Installation

Install debug or release version, in this example we will install the release version.

$ cd Release

Compile qpack

$ make all

Install qpack

$ sudo make install

Note: run sudo make uninstall for removal.

Usage

The following data structure will be packed and unpacked to illustrate how qpack can be used:

{
    "What is the answer to life the universe and everything?": 42
}

Packer

First we start to pack the data.

#include <qpack.h>
#include <assert.h>
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include <inttypes.h>

const char * q = "What is the answer to life the universe and everything?";
const int a = 42;

int main(void)
{
    qp_packer_t * packer = qp_packer_create(512);
    if (packer == NULL) {
        abort();
    }

    /* Open a map. */
    qp_add_map(&packer);

    /* Add a key. We will add the question. Note that the question will be
     * packed without the terminator (null) character. */
    qp_add_raw(packer, q, strlen(q));

    /* Add a value. QPack only supports signed integers. */
    qp_add_int64(packer, (int64_t) a);

    /* Close the map. Note that in a map an even number of items must be placed
     * which represent key/value pairs. */
    qp_close_map(packer);

    /* Print the packed data */
    qp_packer_print(packer);

    /* cleanup the packer */
    qp_packer_destroy(packer);

    return 0;
}

Unpacker

Now we create some code to unpack the data.

void print_qa(const unsigned char * data, size_t len)
{
    qp_unpacker_t unpacker;
    qp_res_t * res;
    int rc;

    /* Initialize the unpacker */
    qp_unpacker_init(&unpacker, data, len);

    /* We can get the data from the unpacker in two ways. One is to step over
     * the data using qp_next() and the other is to unpack all to a qp_res_t
     * object. The last option is probably easier and is what we will use in
     * this example but note that it consumes more memory and is potentially
     * slower compared to qp_next() for some use cases. One more important
     * difference is that qp_res_t contains null terminated copies for raw data
     * which means that this function cannot be used in case raw data contains
     * null characters by themself. */

    res = qp_unpacker_res(&unpacker, &rc);
    if (rc) {
        fprintf(stderr, "error: %s\n", qp_strerror(rc));
    } else {
        /* Usually you should check your response not with assertions */
        assert (res->tp == QP_RES_MAP);
        assert (res->via.map->n == 1); /* one key/value pair */
        assert (res->via.map->keys[0].tp == QP_RES_STR);   /* key */
        assert (res->via.map->values[0].tp == QP_RES_INT64); /* val */

        printf(
            "Unpacked:\n"
            "  Question: %s\n"
            "  Answer  : %" PRId64 "\n",
            res->via.map->keys[0].via.str,
            res->via.map->values[0].via.int64);

        /* cleanup res */
        qp_res_destroy(res);
    }
}

/* Call the function from main (see packer example for full code) */
int main(void)
{
    // ... see packer example for full code

    /* Call print_qa() before destroying the packer using member property
     * qp_packer_t.buffer which contains the packer data and qp_packer_t.len
     * for the size of the data */
    print_qa(packer->buffer, packer->len);

    /* cleanup the packer */
    qp_packer_destroy(packer);

    return 0;
}

API

`qp_packer_t`

Object which is used to pack data.

Public members

unsigned char * qp_packer_t.buffer: contains the packed data (readonly)
size_t qp_packer_t.len: the length of the data (readonly)

`qp_packer_t * qp_packer_create(size_t alloc_size)`

Create and return a new packer instance. Argument alloc_size should be at least greather than 0 since this value is used to allocate memory. When more memory is required while packing data the size will grow in steps of alloc_size.