File SolidSyslogDatagram.h¶

FileList > Core > Interface > SolidSyslogDatagram.h

#include <stdbool.h>
#include <stddef.h>
#include "SolidSyslogExternC.h"

Detailed Description¶

The datagram role: connectionless send of one message to an address (Open / SendTo / Close), with a path-MTU hint (MaxPayload).

These calls dispatch to the injected datagram's vtable, so behaviour is that datagram's.

Public Types Documentation¶

SolidSyslogDatagramSendResult¶

enum SolidSyslogDatagramSendResult {
    SOLIDSYSLOG_DATAGRAM_SEND_RESULT_SENT,
    SOLIDSYSLOG_DATAGRAM_SEND_RESULT_OVERSIZE,
    SOLIDSYSLOG_DATAGRAM_SEND_RESULT_FAILED
};

Public Functions Documentation¶

SolidSyslogDatagram_Close¶

Release the transport acquired by Open.

void SolidSyslogDatagram_Close (
    struct SolidSyslogDatagram * datagram
)

Idempotent; safe on an unopened datagram.

SolidSyslogDatagram_MaxPayload¶

Largest datagram payload the current path is known to accept, used to trim after an OVERSIZE.

size_t SolidSyslogDatagram_MaxPayload (
    struct SolidSyslogDatagram * datagram
)

Falls back to SOLIDSYSLOG_UDP_IPV6_SAFE_PAYLOAD (the IPv6-minimum-MTU floor) before a path MTU is known or when the OS cannot report one.

SolidSyslogDatagram_Open¶

Ready the transport for SendTo (acquire the socket).

bool SolidSyslogDatagram_Open (
    struct SolidSyslogDatagram * datagram
)

Failure leaves the datagram unopened; the sender retries on the next servicing pass.

SolidSyslogDatagram_SendTo¶

Send size bytes ofbuffer toaddr as one datagram.

enum SolidSyslogDatagramSendResult SolidSyslogDatagram_SendTo (
    struct SolidSyslogDatagram * datagram,
    const void * buffer,
    size_t size,
    const struct SolidSyslogAddress * addr
)

addr is borrowed for the call only. A SENT result licenses the sender to drop the record, so a Null datagram returns SENT to discard silently rather than let undeliverables accumulate in the store.

Return value:

SOLIDSYSLOG_DATAGRAM_SEND_RESULT_SENT Delivered to the network.
SOLIDSYSLOG_DATAGRAM_SEND_RESULT_OVERSIZE Too large for the path; the sender trims to MaxPayload and retries.
SOLIDSYSLOG_DATAGRAM_SEND_RESULT_FAILED Transient failure; the record is kept.

FAILED is transient by design: its usual causes - an unreachable collector, a wrong address or port, a stack not yet up - are resolved outside the library, and holding the record until they are is what an audit trail wants. Size is the one cause the record itself carries.

The trim is reactive: the sender offers the record at full size and only calls SolidSyslogDatagram_MaxPayload once OVERSIZE comes back. So on an implementation that collapses OVERSIZE into FAILED, an over-large record is never trimmed. It reaches the stack whole, and if the stack rejects it the failure is permanent while being treated as transient: the record stays at the store's cursor and is offered again on every servicing pass, so nothing behind it is delivered either. Which platforms that affects is on their pages.

The documentation for this class was generated from the following file Core/Interface/SolidSyslogDatagram.h