ose_error.h

/*
  The error record: one shape for every fallible operation.
 
  PLAN-ERROR-REPORTING.md Stage 0b. Lives here rather than in the hosts
  deliberately. Every host that had one carried the same /exception handler,
  and they were wrong in the same way -- a scan of items 1..4 for the first
  string -- because the loop had been pasted into each. Record traversal is
  shared logic and belongs in one place; only PRINTING is host-specific, so
  the reader hands back a pointer and each host prints it its own way.
 
  The record is a message addressed /error carrying a single `|` bundle item
  of addressed fields:
 
      /error : { /error/code    : <int32>
                 /error/message : "<short human text>"
                 ... producer-specific fields ... }
 
  A message rather than a bare bundle because, by the OSC root rule, a bundle
  element has no address, and the /exception handlers find the record BY
  address. /error/code and /error/message are always present, so a host with
  no formatter -- an MCU, a first binding -- prints /error/message and is
  done.
*/
#ifndef OSE_ERROR_H
#define OSE_ERROR_H
 
#ifdef __cplusplus
extern "C" {
#endif
 
#include "ose.h"

#define OSE_ADDR_ERROR "/error"

#define OSE_ADDR_EXCEPTION "/exception"

void ose_error_push(ose_bundle B,
                       int32_t nextra,
                       int32_t code,
                       const char * const message);

const char *ose_error_text(ose_bundle B, int32_t offset);

int32_t ose_error_find(ose_bundle B);

int32_t ose_error_next(ose_bundle B, int32_t prev);
 
#ifdef __cplusplus
}
#endif
 
#endif