Converting CBOR to text

Group of functions used to convert CBOR to text form.

This group contains two functions that can be used to convert a CborValue object to a text representation. This module attempts to follow the recommendations from RFC 7049 section 6 “Diagnostic Notation”, though it has a few differences. They are noted below.

TinyCBOR does not provide a way to convert from the text representation back to encoded form. To produce a text form meant to be parsed, CborToJson is recommended instead.

Either of the functions in this section will attempt to convert exactly one CborValue object to text. Those functions may return any error documented for the functions for CborParsing. In addition, if the C standard library stream functions return with error, the text conversion will return with error CborErrorIO.

These functions also perform UTF-8 validation in CBOR text strings. If they encounter a sequence of bytes that is not permitted in UTF-8, they will return CborErrorInvalidUtf8TextString. That includes encoding of surrogate points in UTF-8.

Text format

As described in RFC 7049 section 6 “Diagnostic Notation”, the format is largely borrowed from JSON, but modified to suit CBOR’s different data types. TinyCBOR makes further modifications to distinguish different, but similar values.

CBOR values are currently encoded as follows: The CborPrettyFlags enumerator contains flags to control some aspects of the encoding:

bool convertToUint64(double v, uint64_t * absolute)
void printRecursionLimit(CborStreamFunction stream, void * out)
cbor.h::CborError hexDump(CborStreamFunction stream, void * out, const void * ptr, size_t n)
cbor.h::CborError utf8EscapedDump(CborStreamFunction stream, void * out, const void * ptr, size_t n)
const char * resolve_indicator(const uint8_t * ptr, const uint8_t * end, int flags)
const char * get_indicator(const CborValue * it, int flags)
cbor.h::CborError value_to_pretty(CborStreamFunction stream, void * out, CborValue * it, int flags, int recursionsLeft)
cbor.h::CborError container_to_pretty(CborStreamFunction stream, void * out, CborValue * it, cbor.h::CborType containerType, int flags, int recursionsLeft)
CBOR_API cbor.h::CborError cbor_value_to_pretty_stream(CborStreamFunction streamFunction, void * token, CborValue * value, int flags)

Converts the current CBOR type pointed by value to its textual representation and writes it to the stream by calling the streamFunction.

If an error occurs, this function returns an error code similar to Parsing CBOR streams.

The textual representation can be controlled by the flags parameter (see cbor.h::CborPrettyFlags for more information).

If no error ocurred, this function advances value to the next element. Often, concatenating the text representation of multiple elements can be done by appending a comma to the output stream in between calls to this function.

The streamFunction function will be called with the token value as the first parameter and a printf-style format string as the second, with a variable number of further parameters.

See also

cbor.h::cbor_value_to_pretty(), cbortojson.c::cbor_value_to_json_advance()

enum CborPrettyFlags
CborPrettyNumericEncodingIndicators = 0x01
CborPrettyTextualEncodingIndicators = 0
CborPrettyIndicateIndeterminateLength = 0x02
CborPrettyIndicateIndetermineLength = CborPrettyIndicateIndeterminateLength
CborPrettyIndicateOverlongNumbers = 0x04
CborPrettyShowStringFragments = 0x100
CborPrettyMergeStringFragments = 0
CborPrettyDefaultFlags = CborPrettyIndicateIndeterminateLength