Internal Message Header
=======================

This header contains the C functions needed for using the message format in the p2p.today project.

It automatically includes :doc:`base.h <./base>` and :doc:`BaseConverter.h <./BaseConverter>`

Using this requires a compiled copy of the sha2 hashes, provided in ``c_src/sha/sha2.c``

.. c:type:: typedef struct InternalMessageStruct

    .. c:member:: unsigned char msg_type

        The type of message this is. These are described in :doc:`protocol/flags <../../protocol/flags>`.

    .. c:member:: char *sender

        The message sender's ID

    .. c:member:: size_t sender_len

    .. c:member:: unsigned long long timestamp

        The time at which this message was sent, in UTC seconds since 1/1/1970.

    .. note::

        Members after these are not garunteed to be present. A function to ensure their existence will be
        provided as noted. Otherwise check if their length term is ``0`` to determine existence.

    .. c:member:: char **compression

        An array of possible compression algorigthms

        This can be initialized with :c:func:`setInternalMessageCompressions`

    .. c:member:: size_t *compression_lens

        The length of each compression string, in the same order

    .. c:member:: size_t num_compression

        The number of compression methods

    .. c:member:: char *id

        The checksum/ID of this message

        To ensure this value is set, call :c:func:`ensureInternalMessageID`

    .. c:member:: size_t id_len

    .. c:member:: char *str

        The serialized version of this message

    .. c:member:: size_t str_len

.. c:function:: static InternalMessageStruct *startInternalMessage(const size_t num_packets, const char *type, size_t type_len, const char *sender, const size_t sender_len, const unsigned long long timestamp)

    Constructs an InternalMessageStruct. This copies all given data into a struct, then returns this struct's pointer.

    :param num_packets        The number of items you will pack (must be exact)
    :param type:              The item to place in :c:member:`InternalMessageStruct.msg_type`
    :param sender:            The item to place in :c:member:`InternalMessageStruct.sender`
    :param sender_len:        The length of the above
    :param sender_is_unicode: If true, pack sender as a string, not a buffer
    :param timestamp:         If non-zero, pack timestamp as this value

    :returns: A pointer to the resulting :c:type:`InternalMessageStruct`

    .. warning::

         You must use :c:func:`destroyInternalMessage` on the resulting object, or you will develop a memory leak

.. c:function:: static void destroyInternalMessage(InternalMessageStruct *des)

    :c:func:`free` an :c:type:`InteralMessageStruct` and its members

    :param des: A pointer to the InternalMessageStruct you wish to destroy

.. c:function:: static void setInternalMessageCompressions(InternalMessageStruct *des, char **compression, size_t *compression_lens, size_t num_compressions)

    Sets the compression methods for a particular :c:type:`InternalMessageStruct`. These methods are formatted as an array of strings, an array of lengths, and a
    number of methods. The data is copied, so you inputs can be local variables.

    :param des:               A pointer to the relevant InternalMessageStruct
    :param compression:       An array of compression methods
    :param compression_lens:  An array of lengths for each compression method
    :param num_compressions:  The number of compression methods

.. c:function:: static void ensureInternalMessageID(InternalMessageStruct *des)

    Ensures that the InternalMessageStruct has an ID calculated and assigned

    :param des: A pointer to the relevant InternalMessageStruct

.. c:function:: static void ensureInternalMessageStr(InternalMessageStruct *des)

    Ensures that the InternalMessageStruct has a serialized string calculated and assigned

    :param des: A pointer to the relevant InternalMessageStruct

.. c:function:: static InternalMessageStruct *deserializeInternalMessage(const char *serialized, size_t len, int sizeless)

    Deserializes an uncompressed :c:type:`InternalMessageStruct`. The ``sizeless`` parameter indicates whether the network size
    header is still present on the given string.

    :param serialized:    The serialized message
    :param len:           The length of the serialized message
    :param sizeless:      A boolean which indicates whether the network size header is still present on the given string
    :param errored:       A pointer to a boolean. If this is set with a non-zero value, it indicates that the checksum test failed

    :returns: An equivalent :c:type:`InternalMessageStruct`, or ``NULL`` if there was an error

.. c:function:: static InternalMessageStruct *deserializeCompressedInternalMessage(const char *serialized, size_t len, int sizeless, char **compression, size_t *compression_lens, size_t num_compressions)

    Deserializes a compressed :c:type:`InternalMessageStruct`. The ``sizeless`` parameter indicates whether the network size
    header is still present on the given string.

    :param serialized:        See :c:func:`deserializeInternalMessage`
    :param len:               See :c:func:`deserializeInternalMessage`
    :param sizeless:          See :c:func:`deserializeInternalMessage`
    :param errored:           See :c:func:`deserializeInternalMessage`
    :param compression:       See :c:func:`setInternalMessageCompressions`
    :param compression_lens:  See :c:func:`setInternalMessageCompressions`
    :param num_compressions:  See :c:func:`setInternalMessageCompressions`

    :returns: An equivalent :c:type:`InternalMessageStruct`, or ``NULL`` if there was an error