version: "0.4.2"
classes:
  - name: "BufferTarget"
    doc: >
      A target that will write log messages to a provided buffer, wrapping
      around when the end is reached. A NULL character will be written to the
      end of each message.

      Note that callers must handle the wrap-around case, and not assume that
      each read will end in a NULL character, in case a wrap-around occurs.
    namespace: "stumpless"
    equivalent-struct:
      name: "stumpless_target"
      includes: "stumpless/target.h"
    constructors:
      - doc: >
          Opens a buffer target for the given buffer.
        wrapped-function:
          name: "stumpless_open_buffer_target"
          includes: "stumpless/target/buffer.h"
          params:
            - name: "name"
              doc: "The name of this target."
              type: "const char *"
            - name: "buffer"
              doc: "The buffer to log events to."
              type: "char *"
            - name: "size"
              doc: "The number of characters buffer can hold."
              type:
                name: "size_t"
                includes: "stddef.h"
          return:
            type: "equivalent-struct-pointer"
          use-template: "pointer-return-error-check"
    destructor:
      doc: >
        Closes the target and releases all memory owned by it. Does NOT empty or
        free the buffer.
      wrapped-function:
        name: "stumpless_close_buffer_target"
        includes: "stumpless/target/buffer.h"
        params:
          - value: "equivalent-struct-pointer"
    functions:
      - name: "Read"
        doc: >
          Reads the next message from this target and writes it into the given
          buffer.

          If the buffer has not been read from before messages have wrapped
          around, then you may only get the end of a message. To avoid this
          situation, you will need to read the buffer often enough to stay ahead
          of the written messages. Making sure that the log buffer is
          sufficiently sized may help with this.

          A terminating NULL character will always be written at the end of the
          output. Note that this means that if the read operation was successful
          but there was no message to read, the result will be 1 with a single
          NULL character being written to the read buffer.

          Available since release v2.0.0.
        params:
          - name: "buffer"
            doc: "The buffer to write the message into."
            type: "char *"
          - name: "max_length"
            doc: >
              The maximum number of bytes to write into the provided buffer.
            type:
              name: "size_t"
              includes: "stddef.h"
        return:
          doc: >
            The number of bytes written into the buffer, including the
            terminating NULL character.
          type:
            name: "size_t"
            includes: "stddef.h"
        wrapped-function:
          name: "stumpless_read_buffer"
          includes: "stumpless/target/buffer.h"
          params:
            - value: "equivalent-struct-pointer"
            - value: "buffer"
            - value: "max_length"
          return:
            type:
              name: "size_t"
              includes: "stddef.h"
      - use-template: "common-target-functions"