version: "0.4.2"
enums:
  - name: "NetworkProtocol"
    doc: "Network protocols used by network targets."
    namespace: "stumpless"
    includes: "stumpless/target/network.h"
    elements:
      - name: "IPV4"
        doc: "Internet Protocol version 4, RFC 791"
        value: "STUMPLESS_IPV4_NETWORK_PROTOCOL"
      - name: "IPV6"
        doc: "Internet Protocl version 6, RFC 8200"
        value: "STUMPLESS_IPV6_NETWORK_PROTOCOL"
  - name: "TransportProtocol"
    doc: "Transport protocols used by network targets."
    namespace: "stumpless"
    includes: "stumpless/target/network.h"
    elements:
      - name: "TCP"
        doc: "TCP, RFC 793"
        value: "STUMPLESS_TCP_TRANSPORT_PROTOCOL"
      - name: "UDP"
        doc: "UDP, RFC 768"
        value: "STUMPLESS_UDP_TRANSPORT_PROTOCOL"
classes:
  - name: "NetworkTarget"
    doc: >
      Network targets allow traditional syslog messages to be sent to a remote
      server. These can use either UDP or TCP over either IPv4 or IPv6.
    namespace: "stumpless"
    equivalent-struct:
      name: "stumpless_target"
      includes: "stumpless/target.h"
    constants:
      - name: "DEFAULT_TRANSPORT_PORT"
        doc: >
          The default transport port for network targets.

          This is based largely on tradition, but some applications may expect a
          different port (for example 1514 and 6514 are sometimes used). If a
          different port is needed on a target, use SetTransportPort to change
          it.
        type: "char *"
        value: "STUMPLESS_DEFAULT_TRANSPORT_PORT"
        includes: "stumpless/target/network.h"
      - name: "DEFAULT_UDP_MAX_MESSAGE_SIZE"
        doc: >
          The default message size for UDP network targets.

          This is set to account for an MTU of 1500 bytes, a 20 byte IP header,
          and an 8 byte datagram header. If you wish to change this value for a
          particular target, then you must use SetUdpMaxMessageSize to change
          it.
        type: "size_t"
        value: "STUMPLESS_DEFAULT_UDP_MAX_MESSAGE_SIZE"
        includes:
          - "stddef.h"
          - "stumpless/target/network.h"
    constructors:
      - doc: >
          Creates a new network target with the given parameters and opens it.
        wrapped-function:
          name: "stumpless_open_network_target"
          includes: "stumpless/target/network.h"
          params:
            - name: "name"
              doc: "The name of this network target."
              type: "const char *"
            - name: "destination"
              doc: >
                The destination to send messages to. This could be a hostname or
                an IP address.
              type: "const char *"
            - name: "network_protocol"
              doc: "The network protocol to use."
              type:
                name: "NetworkProtocol"
                includes: "NetworkProtocol.hpp"
              value: "static_cast<stumpless_network_protocol>(network_protocol)"
            - name: "transport_protocol"
              doc: "The transport protocol to use."
              type:
                name: "TransportProtocol"
                includes: "TransportProtocol.hpp"
              value: "static_cast<stumpless_transport_protocol>(transport_protocol)"
          return:
            type: "equivalent-struct-pointer"
          use-template: "pointer-return-error-check"
    destructor:
      doc: >
        Closes this target and releases all memory and other resources held by
        it.
      wrapped-function:
        name: "stumpless_close_network_target"
        includes: "stumpless/target/network.h"
        params:
          - name: "equivalent-struct-pointer"
    functions:
      - use-template: "common-target-functions"
      - name: "GetDestination"
        doc: "Gets the destination of the target."
        return:
          doc: "The current destination of the target."
          type: "const char *"
        wrapped-function:
          name: "stumpless_get_destination"
          params:
            - value: "equivalent-struct-pointer"
          return:
            type: "const char *"
      - name: "GetTransportPort"
        doc: "Gets the transport port number of the target."
        return:
          doc: >
            The current port number of the network taret, encoded as a
            NULL-terminated string.
          type: "const char *"
        wrapped-function:
          name: "stumpless_get_transport_port"
          params:
            - value: "equivalent-struct-pointer"
          return:
            type: "const char *"
      - name: "GetUdpMaxMessageSize"
        doc: "Gets the current maximum message size of a UDP network target"
        return:
          doc: "The current maximum message size of the target."
          type: "size_t"
          includes: "stddef.h"
        wrapped-function:
          name: "stumpless_get_udp_max_message_size"
          params:
            - value: "equivalent-struct-pointer"
          return:
            type: "size_t"
      - name: "NewPausedTarget"
        doc: >
          Creates a new network target with the given parameters but does not
          open it.

          This function is useful if additional settings need to be set before
          initiating a network connection, such as the transport port or the
          maximum UDP message size.
        static: true
        params:
          - name: "name"
            doc: "The name of this network target."
            type: "const char *"
          - name: "network_protocol"
            doc: "The network protocol to use."
            type:
              name: "NetworkProtocol"
              includes: "NetworkProtocol.hpp"
          - name: "transport_protocol"
            doc: "The transport protocol to use."
            type:
              name: "TransportProtocol"
              includes: "TransportProtocol.hpp"
        return:
          doc: "The newly created NetworkTarget."
          type: "NetworkTarget"
        wrapped-function:
          name: "stumpless_new_network_target"
          params:
            - value: "name"
            - value: "static_cast<stumpless_network_protocol>(network_protocol)"
            - value: "static_cast<stumpless_transport_protocol>(transport_protocol)"
      - name: "NewPausedTcp4Target"
        doc: >
          Creates a new network target using TCP over IPv4 with the given name.

          This is equivalent to calling NewPausedTarget with
          NetworkProtocol::IPV4 and TransportProtocol::TCP as parameters.
        static: true
        params:
          - name: "name"
            doc: "The name of this network target."
            type: "const char *"
        return:
          doc: "The newly created NetworkTarget."
          type: "NetworkTarget"
        wrapped-function:
          name: "stumpless_new_tcp4_target"
          params:
            - value: "name"
      - name: "NewPausedTcp6Target"
        doc: >
          Creates a new network target using TCP over IPv6 with the given name.

          This is equivalent to calling NewPausedTarget with
          NetworkProtocol::IPV6 and TransportProtocol::TCP as parameters.
        static: true
        params:
          - name: "name"
            doc: "The name of this network target."
            type: "const char *"
        return:
          doc: "The newly created NetworkTarget."
          type: "NetworkTarget"
        wrapped-function:
          name: "stumpless_new_tcp6_target"
          params:
            - value: "name"
      - name: "NewPausedUdp4Target"
        doc: >
          Creates a new network target using UDP over IPv4 with the given name.

          This is equivalent to calling NewPausedTarget with
          NetworkProtocol::IPV4 and TransportProtocol::UDP as parameters.
        static: true
        params:
          - name: "name"
            doc: "The name of this network target."
            type: "const char *"
        return:
          doc: "The newly created NetworkTarget."
          type: "NetworkTarget"
        wrapped-function:
          name: "stumpless_new_udp4_target"
          params:
            - value: "name"
      - name: "NewPausedUdp6Target"
        doc: >
          Creates a new network target using UDP over IPv6 with the given name.

          This is equivalent to calling NewPausedTarget with
          NetworkProtocol::IPV6 and TransportProtocol::UDP as parameters.
        static: true
        params:
          - name: "name"
            doc: "The name of this network target."
            type: "const char *"
        return:
          doc: "The newly created NetworkTarget."
          type: "NetworkTarget"
        wrapped-function:
          name: "stumpless_new_udp6_target"
          params:
            - value: "name"
      - name: "OpenTcp4Target"
        doc: >
          Creates a new network network target using TCP over IPv4 with the
          given parameters and opens it.

          This is equivalent to calling the constructor with
          NetworkProtocol::IPV4 and TransportProtocol::TCP as parameters.
        static: true
        params:
          - name: "name"
            doc: "The name of this network target."
            type: "const char *"
          - name: "destination"
            doc: >
              The destination to send messages to. This could be a hostname or
              an IP address.
            type: "const char *"
        return:
          doc: "The newly created NetworkTarget."
          type: "NetworkTarget"
        wrapped-function:
          name: "stumpless_open_tcp4_target"
          includes: "stumpless/target/network.h"
          params:
            - value: "name"
            - value: "destination"
      - name: "OpenTcp6Target"
        doc: >
          Creates a new network network target using TCP over IPv6 with the
          given parameters and opens it.

          This is equivalent to calling the constructor with
          NetworkProtocol::IPV6 and TransportProtocol::TCP as parameters.
        static: true
        params:
          - name: "name"
            doc: "The name of this network target."
            type: "const char *"
          - name: "destination"
            doc: >
              The destination to send messages to. This could be a hostname or
              an IP address.
            type: "const char *"
        return:
          doc: "The newly created NetworkTarget."
          type: "NetworkTarget"
        wrapped-function:
          name: "stumpless_open_tcp6_target"
          includes: "stumpless/target/network.h"
          params:
            - value: "name"
            - value: "destination"
      - name: "OpenUdp4Target"
        doc: >
          Creates a new network network target using UDP over IPv4 with the
          given parameters and opens it.

          This is equivalent to calling the constructor with
          NetworkProtocol::IPV4 and TransportProtocol::UDP as parameters.
        static: true
        params:
          - name: "name"
            doc: "The name of this network target."
            type: "const char *"
          - name: "destination"
            doc: >
              The destination to send messages to. This could be a hostname or
              an IP address.
            type: "const char *"
        return:
          doc: "The newly created NetworkTarget."
          type: "NetworkTarget"
        wrapped-function:
          name: "stumpless_open_udp4_target"
          includes: "stumpless/target/network.h"
          params:
            - value: "name"
            - value: "destination"
      - name: "OpenUdp6Target"
        doc: >
          Creates a new network network target using UDP over IPv6 with the
          given parameters and opens it.

          This is equivalent to calling the constructor with
          NetworkProtocol::IPV6 and TransportProtocol::UDP as parameters.
        static: true
        params:
          - name: "name"
            doc: "The name of this network target."
            type: "const char *"
          - name: "destination"
            doc: >
              The destination to send messages to. This could be a hostname or
              an IP address.
            type: "const char *"
        return:
          doc: "The newly created NetworkTarget."
          type: "NetworkTarget"
        wrapped-function:
          name: "stumpless_open_udp6_target"
          includes: "stumpless/target/network.h"
          params:
            - value: "name"
            - value: "destination"
      - name: "SetDestination"
        doc: >
          Sets the destination of the target.

          If the target is already open when this function is called, then it
          will attempt to re-open the target after the destination is changed.
          If the target is in a paused state, then it will be left that way
          until an explicit call to Open is made.
        params:
          - name: "destination"
            doc: "The new destination to use."
            type: "const char *"
        return:
          doc: "The modified target."
          type: "self-reference"
        wrapped-function:
          name: "stumpless_set_destination"
          params:
            - value: "equivalent-struct-pointer"
            - value: "destination"
          return:
            type: "struct stumpless_target *"
          use-template: "pointer-return-error-check"
      - name: "SetTransportPort"
        doc: >
          Sets the transport port of the target.

          If the target is already open when this function is called, then it
          will attempt to re-open the target after the port is changed. If the
          target is in a paused state, then it will be left that way until an
          explicit call to Open is made.
        params:
          - name: "port"
            doc: "The new port to use. as a NULL-terminated string."
            type: "const char *"
        return:
          doc: "The modified target."
          type: "self-reference"
        wrapped-function:
          name: "stumpless_set_transport_port"
          params:
            - value: "equivalent-struct-pointer"
            - value: "port"
          return:
            type: "struct stumpless_target *"
          use-template: "pointer-return-error-check"
      - name: "SetUdpMaxMessageSize"
        doc: >
          Sets the maximum message size of a UDP network target.

          Messages that are longer than the maximum size are truncated to this
          length. If the underlying transport for a network target can support a
          larger datagram and you need support for longer messages, then you can
          use this option to increase the size. Likewise, the option can be used
          to force smaller datagrams if needed, for example in the case of extra
          overhead in the IP header beyond the typical 20 bytes.

          Note that truncations due to the maximum size do not take UTF
          characters into account. If you have entries using multi-byte
          characters, then you need to be sure that these truncations do not
          cause parsing or security problems.

          Without calling this function, UDP targets start with a maximum
          message size set to DEFAULT_UDP_MAX_MESSAGE_SIZE.
        params:
          - name: "max_msg_size"
            doc: "The new maximum message size for this target."
            type:
              name: "size_t"
              includes: "stddef.h"
        return:
          doc: "The modified target."
          type: "self-reference"
        wrapped-function:
          name: "stumpless_set_udp_max_message_size"
          params:
            - value: "equivalent-struct-pointer"
            - value: "max_msg_size"
          return:
            type: "struct stumpless_target *"
          use-template: "pointer-return-error-check"