PB_DECODE(3)

NAME
pb_decode, pb_decode_from_memory - protocol buffers decoding

LIBRARY
Protocol buffers library (libpicopb, -lpicopb)

SYNOPSIS
#include <pb.h>
#include <pb_decode.h>
int
pb_decode(struct pb_msg msg, int (*callback)(void *cookie, void *buf, size_t *lenp), void *cookie);
int
pb_decode_from_memory(struct pb_msg msg, const void *buf, size_t len);

DESCRIPTION
The pb_decode functions decode protobuf messages in binary wire format.

Messages must have been previously initialized with pb_init(3).

FUNCTIONS

pb_decode(msg, callback, cookie)
    Decode msg from data supplied by calling callback(cookie, buf, lenp), which must fill buf with up to *lenp bytes and store the number of bytes actually filled in *lenp. The callback may return zero to indicate success or an errno(2) error code to indicate failure, which will be returned by pb_encode().

    The message msg must have been initialized with pb_init(3).

    Returns zero on success or an errno(2) error code on failure, possibly after modifying msg.

pb_decode_from_memory(msg, buf, len)
    Decodes msg from len bytes of data at buf.

    Returns zero on success or an errno(2) error code on failure, possibly after modifying msg.

EXAMPLES
Decode a message from a buffer in memory:

            void *buf = ...;
            size_t size = ...;
            struct Msg m;
            int error;
            pb_init(Msg(&m));
            error = pb_decode_from_memory(Msg(&m), buf, size);
            if (error)
                    goto out;
            /* Use m.  */
            do_something(m.frobnitz);
            ...
    out:    pb_destroy(Msg(&m));
            return error;

Decode a message read from a file stream:

    static int
    decode_file_callback(void *cookie, void *buf, size_t *np)
    {
    	FILE *file = cookie;
    	size_t nreq, nread;
    	nreq = *np;
    	nread = fread(buf, 1, nreq, file);
    	if (nread < nreq && ferror(file))
    		return errno;
    	*np = nread;
    	return 0;
    }
    ...
    {
            FILE *file = ...;
            struct Msg m;
            int error;
            pb_init(Msg(&m));
            error = pb_decode(Msg(&m), &decode_file_callback, file);
            if (error)
                    goto out;
            /* Use m.  */
            do_something(m.frobnitz);
            ...
    out:    pb_destroy(Msg(&m));
            return error;
    }

ERRORS
The pb_decode() function may fail for any reason returned by the caller-supplied callback. Additionally, pb_decode() and pb_decode_from_memory() may fail for the following other reasons:

[EILSEQ]
    A string in the input contained a sequence of octets other than a valid UTF-8 sequence.

[EINVAL]
    The message msg or one of its submessages was not initialized with pb_init(3).

[EIO]
    The input was malformed.

SEE ALSO
picopbc(1), errno(2), pb(3), pb_encode(3)

AUTHORS
Taylor R Campbell <campbell+picopb@mumble.net>

BUGS
It is not clear that pb_decode() and pb_decode_from_memory() should return EINVAL instead of crashing altogether if msg was not properly initialized.