PB_ENCODE(3)

NAME
pb_encode, pb_encode_to_memory, pb_encoding_size - protocol buffers encoding

LIBRARY
Protocol buffers library (libpicopb, -lpicopb)

SYNOPSIS
#include <pb.h>
#include <pb_encode.h>
int
pb_encoding_size(struct pb_msg msg, size_t *sizep);
int
pb_encode(struct pb_msg msg, int (*callback)(void *cookie, const void *buf, size_t len), void *cookie);
int
pb_encode_to_memory(struct pb_msg msg, void *buf, size_t len);

DESCRIPTION
The pb_encode functions encode protobuf messages in binary wire format.

Messages must have been previously initialized with pb_init(3), and callers must call pb_encoding_size() to determine the size of a message, and all its submessages, after any modification to the message or submessages before calling pb_encode() or pb_encode_to_memory().

The pb_encoding_size() function modifies msg; the pb_encode() and pb_encode_to_memory() functions do not. Beware sharing protobuf messages between threads.

FUNCTIONS

pb_encoding_size(msg, sizep)
    Compute the encoding size of msg in bytes and store it in *sizep.

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

    Returns zero on success or an errno(2) error code on failure.

pb_encode(msg, callback, cookie)
    Encode msg in binary wire format, calling callback(cookie, buf, len) to write len bytes of output at buf. 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), and the caller must first call pb_encoding_size() to determine the encoding size of msg and its submessages after all modifications to msg before calling pb_encode().

    Returns zero on success or an errno(2) error code on failure.

pb_encode_to_memory(msg, buf, len)
    Encodes msg into the buffer of len bytes starting at buf.

    The message msg must have been initialized with pb_init(3), and the caller must first call pb_encoding_size() to determine the encoding size of msg and its submessages after all modifications to msg before calling pb_encode_to_memory().

    Returns zero on success or an errno(2) error code on failure.

EXAMPLES
Allocate a buffer to fit a message:

            struct Msg m;
            void *buf;
            size_t size;
            int error;
            /* Initialize and fill m.  */
            pb_init(Msg(&m));
            m.frobnitz = 123;
            ...
            error = pb_encoding_size(Msg(&m), &size);
            if (error)
                    goto out;
            buf = malloc(size);
            if (buf == NULL)
                    goto out;
            error = pb_encode_to_memory(Msg(&m), buf, size);
            if (error)
                    goto out;
            /* Use buf.  */
            do_something(buf, size);
            ...
    out:    pb_destroy(Msg(&m));
            return error;

Write a message to a file stream:

    static int
    encode_file_callback(void *cookie, const void *buf, size_t len)
    {
            FILE *const file = cookie;
            if (fwrite(buf, len, 1, file) < 1)
                    return errno;
            return 0;
    }
    ...
    {
            FILE *file = ...;
            struct Msg m;
            size_t size;
            int error;
            /* Initialize and fill m.  */
            pb_init(Msg(&m));
            m.frobnitz = 123;
            ...
    	/*
             * Compute the encoding size.  We don't need it, but
             * pb_encode does for the wire format of submessages.
             */
            error = pb_encoding_size(Msg(&m), &size);
            if (error)
                    goto out;
            (void)size;	/* ignore */
            error = pb_encode(Msg(&m), &encode_file_callback, file);
            if (error)
                    goto out;
    out:    pb_destroy(Msg(&m));
            return error;
    }

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

[EFBIG]
    The message msg is too large for its size to fit in size_t.

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

[EINVAL]
    The message msg was not sized with pb_encoding_size() before being encoded with pb_encode() or pb_encode_to_memory().

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

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

BUGS
It is not clear that pb_encode(), pb_encode_to_memory(), and pb_encoding_size() should return EINVAL instead of crashing altogether if msg was not properly initialized.