blob: ef2b3546db85256eb803c84cfccc930301cb0f57 [file] [log] [blame]
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "">
<html xmlns="">
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.14"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>TinyCBOR 0.5.2 API: Converting CBOR to text</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tr style="height: 56px;">
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">TinyCBOR 0.5.2 API
<!-- end header part -->
<!-- Generated by Doxygen 1.8.14 -->
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
$(function() {
/* @license-end */</script>
<div id="main-nav"></div>
</div><!-- top -->
<div class="header">
<div class="summary">
<a href="#enum-members">Enumerations</a> &#124;
<a href="#func-members">Functions</a> </div>
<div class="headertitle">
<div class="title">Converting CBOR to text</div> </div>
<div class="contents">
<p>Group of functions used to convert CBOR to text form.
<a href="#details">More...</a></p>
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="enum-members"></a>
<tr class="memitem:gacc03414f6f6313d18ae5c56d4167d798"><td class="memItemLeft" align="right" valign="top">enum &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="a00048.html#gacc03414f6f6313d18ae5c56d4167d798">CborPrettyFlags</a> </td></tr>
<tr class="memdesc:gacc03414f6f6313d18ae5c56d4167d798"><td class="mdescLeft">&#160;</td><td class="mdescRight">The CborPrettyFlags enum contains flags that control the conversion of CBOR to text format. <a href="a00048.html#gacc03414f6f6313d18ae5c56d4167d798">More...</a><br /></td></tr>
<tr class="separator:gacc03414f6f6313d18ae5c56d4167d798"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="func-members"></a>
<tr class="memitem:gab43d4414c47f00c74262e0687e23dcda"><td class="memItemLeft" align="right" valign="top"><a class="el" href="a00045.html#ga76e9c9acc63dd940da4ab7e91309f7b5">CborError</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="a00048.html#gab43d4414c47f00c74262e0687e23dcda">cbor_value_to_pretty_stream</a> (CborStreamFunction streamFunction, void *token, <a class="el" href="a00065.html">CborValue</a> *value, int flags)</td></tr>
<tr class="memdesc:gab43d4414c47f00c74262e0687e23dcda"><td class="mdescLeft">&#160;</td><td class="mdescRight">Converts the current CBOR type pointed by <em>value</em> to its textual representation and writes it to the stream by calling the <em>streamFunction</em>. <a href="#gab43d4414c47f00c74262e0687e23dcda">More...</a><br /></td></tr>
<tr class="separator:gab43d4414c47f00c74262e0687e23dcda"><td class="memSeparator" colspan="2">&#160;</td></tr>
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
<p>Group of functions used to convert CBOR to text form. </p>
<p>This group contains two functions that can be used to convert a <a class="el" href="a00065.html">CborValue</a> 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.</p>
<p>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.</p>
<p>Either of the functions in this section will attempt to convert exactly one <a class="el" href="a00065.html" title="This type contains one value parsed from the CBOR stream. ">CborValue</a> 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.</p>
<p>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.</p>
<dl class="section warning"><dt>Warning</dt><dd>The output type produced by these functions is not guaranteed to remain stable. A future update of TinyCBOR may produce different output for the same input and parsers may be unable to handle it.</dd></dl>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="a00047.html" title="Group of functions used to parse CBOR streams. ">Parsing CBOR streams</a>, <a class="el" href="a00049.html" title="Group of functions used to convert CBOR to JSON. ">Converting CBOR to JSON</a>, <a class="el" href="a00047.html#gadb356bb705f2d8239f03b36081a43b4f" title="Initializes the CBOR parser for parsing size bytes beginning at buffer. ">cbor_parser_init()</a></dd></dl>
<h2 class="groupheader">Text format</h2>
<p>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.</p>
<p>CBOR values are currently encoded as follows: </p><dl class="section user"><dt>Integrals (unsigned and negative)</dt><dd>Base-10 (decimal) text representation of the value </dd></dl>
<dl class="section user"><dt>Byte strings:</dt><dd><code>"h'"</code> followed by the Base16 (hex) representation of the binary data, followed by an ending quote (') </dd></dl>
<dl class="section user"><dt>Text strings:</dt><dd>C-style escaped string in quotes, with C11/C++11 escaping of Unicode codepoints above U+007F. </dd></dl>
<dl class="section user"><dt>Tags:</dt><dd>Tag value, with the tagged value in parentheses. No special encoding of the tagged value is performed. </dd></dl>
<dl class="section user"><dt>Simple types:</dt><dd><code>"simple(nn)"</code> where <code>nn</code> is the simple value </dd></dl>
<dl class="section user"><dt>Null:</dt><dd><code>null</code> </dd></dl>
<dl class="section user"><dt>Undefined:</dt><dd><code>undefined</code> </dd></dl>
<dl class="section user"><dt>Booleans:</dt><dd><code>true</code> or <code>false</code> </dd></dl>
<dl class="section user"><dt>Floating point:</dt><dd>If NaN or infinite, the actual words <code>NaN</code> or <code>infinite</code>. Otherwise, the decimal representation with as many digits as necessary to ensure no loss of information. By default, float values are suffixed by "f" and half-float values suffixed by "f16" (doubles have no suffix). If the CborPrettyNumericEncodingIndicators flag is active, the values instead are encoded following the Section 6 recommended encoding indicators: float values are suffixed with "_2" and half-float with "_1". A decimal point is always present. </dd></dl>
<dl class="section user"><dt>Arrays:</dt><dd>Comma-separated list of elements, enclosed in square brackets ("[" and "]"). </dd></dl>
<dl class="section user"><dt>Maps:</dt><dd>Comma-separated list of key-value pairs, with the key and value separated by a colon (":"), enclosed in curly braces ("{" and "}").</dd></dl>
<p>The CborPrettyFlags enumerator contains flags to control some aspects of the encoding: </p><dl class="section user"><dt>String fragmentation</dt><dd>When the CborPrettyShowStringFragments option is active, text and byte strings that are transmitted in fragments are shown instead inside parentheses ("(" and ")") with no preceding number and each fragment is displayed individually. If a tag precedes the string, then the output will contain a double set of parentheses. If the option is not active, the fragments are merged together and the display will not show any difference from a string transmitted with determinate length. </dd></dl>
<dl class="section user"><dt>Encoding indicators</dt><dd>Numbers and lengths in CBOR can be encoded in multiple representations. If the CborPrettyIndicateOverlongNumbers option is active, numbers and lengths that are transmitted in a longer encoding than necessary will be indicated, by appending an underscore ("_") to either the number or the opening bracket or brace, followed by a number indicating the CBOR additional information: 0 for 1 byte, 1 for 2 bytes, 2 for 4 bytes and 3 for 8 bytes. If the CborPrettyIndicateIndeterminateLength option is active, maps, arrays and strings encoded with indeterminate length will be marked by an underscore after the opening bracket or brace or the string (if not showing fragments), without a number after it. </dd></dl>
<h2 class="groupheader">Enumeration Type Documentation</h2>
<a id="gacc03414f6f6313d18ae5c56d4167d798"></a>
<h2 class="memtitle"><span class="permalink"><a href="#gacc03414f6f6313d18ae5c56d4167d798">&#9670;&nbsp;</a></span>CborPrettyFlags</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<td class="memname">enum <a class="el" href="a00048.html#gacc03414f6f6313d18ae5c56d4167d798">CborPrettyFlags</a></td>
</div><div class="memdoc">
<p>The CborPrettyFlags enum contains flags that control the conversion of CBOR to text format. </p>
<li><code>CborPrettyNumericEncodingIndicators</code> Use numeric encoding indicators instead of textual for float and half-float. </li>
<li><code>CborPrettyTextualEncodingIndicators</code> Use textual encoding indicators for float ("f") and half-float ("f16"). </li>
<li><code>CborPrettyIndicateIndeterminateLength</code> (default) Indicate when a map or array has indeterminate length. </li>
<li><code>CborPrettyIndicateOverlongNumbers</code> Indicate when a number or length was encoded with more bytes than needed. </li>
<li><code>CborPrettyShowStringFragments</code> If the byte or text string is transmitted in chunks, show each individually. </li>
<li><code>CborPrettyMergeStringFragment</code> Merge all chunked byte or text strings and display them in a single entry. </li>
<li><code>CborPrettyDefaultFlags</code> Default conversion flags. </li>
<h2 class="groupheader">Function Documentation</h2>
<a id="gab43d4414c47f00c74262e0687e23dcda"></a>
<h2 class="memtitle"><span class="permalink"><a href="#gab43d4414c47f00c74262e0687e23dcda">&#9670;&nbsp;</a></span>cbor_value_to_pretty_stream()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<td class="memname"><a class="el" href="a00045.html#ga76e9c9acc63dd940da4ab7e91309f7b5">CborError</a> cbor_value_to_pretty_stream </td>
<td class="paramtype">CborStreamFunction&#160;</td>
<td class="paramname"><em>streamFunction</em>, </td>
<td class="paramkey"></td>
<td class="paramtype">void *&#160;</td>
<td class="paramname"><em>token</em>, </td>
<td class="paramkey"></td>
<td class="paramtype"><a class="el" href="a00065.html">CborValue</a> *&#160;</td>
<td class="paramname"><em>value</em>, </td>
<td class="paramkey"></td>
<td class="paramtype">int&#160;</td>
<td class="paramname"><em>flags</em>&#160;</td>
</div><div class="memdoc">
<p>Converts the current CBOR type pointed by <em>value</em> to its textual representation and writes it to the stream by calling the <em>streamFunction</em>. </p>
<p>If an error occurs, this function returns an error code similar to <a class="el" href="a00047.html">Parsing CBOR streams</a>.</p>
<p>The textual representation can be controlled by the <em>flags</em> parameter (see <a class="el" href="a00048.html#gacc03414f6f6313d18ae5c56d4167d798">CborPrettyFlags</a> for more information).</p>
<p>If no error ocurred, this function advances <em>value</em> 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.</p>
<p>The <em>streamFunction</em> function will be called with the <em>token</em> value as the first parameter and a printf-style format string as the second, with a variable number of further parameters.</p>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="a00005.html#a0529f04ea9045bbd351ea03ee0a21b7b" title="Converts the current CBOR type pointed to by value to its textual representation and writes it to the...">cbor_value_to_pretty()</a>, <a class="el" href="a00049.html#ga558485bab0ebcb2646e7669d13861d79" title="Converts the current CBOR type pointed to by value to JSON and writes that to the out stream...">cbor_value_to_json_advance()</a> </dd></dl>
<p class="reference">Referenced by <a class="el" href="a00005.html#aef4d5dc4b2bfaf458e82e350509f9c30">cbor_value_to_pretty_advance()</a>, and <a class="el" href="a00005.html#adba89091b9618b1b6daa22284321cce7">cbor_value_to_pretty_advance_flags()</a>.</p>
</div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by &#160;<a href="">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.14