blob: 3dbabbd93a5e104ebbb0130595d7385c8cdb36cc [file] [log] [blame]
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<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.6"/>
<title>TinyCBOR API: Converting CBOR to JSON</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" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td style="padding-left: 0.5em;">
<div id="projectname">TinyCBOR API
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.6 -->
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main&#160;Page</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li><a href="annotated.html"><span>Data&#160;Structures</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
</ul>
</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 JSON</div> </div>
</div><!--header-->
<div class="contents">
<p>Group of functions used to convert CBOR to JSON.
<a href="#details">More...</a></p>
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="enum-members"></a>
Enumerations</h2></td></tr>
<tr class="memitem:ga2f7386ebce337e0de69cae456bda78f7"><td class="memItemLeft" align="right" valign="top">enum &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="a00021.html#ga2f7386ebce337e0de69cae456bda78f7">CborToJsonFlags</a> </td></tr>
<tr class="memdesc:ga2f7386ebce337e0de69cae456bda78f7"><td class="mdescLeft">&#160;</td><td class="mdescRight">The CborToJsonFlags enum contains flags that control the conversion of CBOR to JSON. <a href="a00021.html#ga2f7386ebce337e0de69cae456bda78f7">More...</a><br/></td></tr>
<tr class="separator:ga2f7386ebce337e0de69cae456bda78f7"><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>
Functions</h2></td></tr>
<tr class="memitem:ga558485bab0ebcb2646e7669d13861d79"><td class="memItemLeft" align="right" valign="top"><a class="el" href="a00017.html#ga76e9c9acc63dd940da4ab7e91309f7b5">CborError</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="a00021.html#ga558485bab0ebcb2646e7669d13861d79">cbor_value_to_json_advance</a> (FILE *out, <a class="el" href="a00002.html">CborValue</a> *value, int flags)</td></tr>
<tr class="memdesc:ga558485bab0ebcb2646e7669d13861d79"><td class="mdescLeft">&#160;</td><td class="mdescRight">Converts the current CBOR type pointed by <em>value</em> to JSON and writes that to the <em>out</em> stream. <a href="#ga558485bab0ebcb2646e7669d13861d79">More...</a><br/></td></tr>
<tr class="separator:ga558485bab0ebcb2646e7669d13861d79"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga3f2ce7eadf9a355654186166d24e69cf"><td class="memItemLeft" align="right" valign="top"><a class="el" href="a00017.html#ga76e9c9acc63dd940da4ab7e91309f7b5">CborError</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="a00021.html#ga3f2ce7eadf9a355654186166d24e69cf">cbor_value_to_json</a> (FILE *out, const <a class="el" href="a00002.html">CborValue</a> *value, int flags)</td></tr>
<tr class="memdesc:ga3f2ce7eadf9a355654186166d24e69cf"><td class="mdescLeft">&#160;</td><td class="mdescRight">Converts the current CBOR type pointed by <em>value</em> to JSON and writes that to the <em>out</em> stream. <a href="#ga3f2ce7eadf9a355654186166d24e69cf">More...</a><br/></td></tr>
<tr class="separator:ga3f2ce7eadf9a355654186166d24e69cf"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table>
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
<p>Group of functions used to convert CBOR to JSON. </p>
<p>This group contains two functions that are can be used to convert one <a class="el" href="a00002.html" title="This type contains one value parsed from the CBOR stream. ">CborValue</a> object to an equivalent JSON representation. This module attempts to follow the recommendations from RFC 7049 section 4.1 "Converting from
CBOR to JSON", though it has a few differences. They are noted below.</p>
<p>These functions produce a "minified" JSON output, with no spacing, indentation or line breaks. If those are necessary, they need to be applied in a post-processing phase.</p>
<p>Note that JSON cannot support all CBOR types with fidelity, so the conversion is usually lossy. For that reason, TinyCBOR supports adding a set of metadata JSON values that can be used by a JSON-to-CBOR converter to restore the original data types.</p>
<p>The TinyCBOR library does not provide a way to convert from JSON representation back to encoded form. However, it provides a tool called <code>json2cbor</code> which can be used for that purpose. That tool supports the metadata format that these functions may produce.</p>
<p>Either of the functions in this section will attempt to convert exactly one <a class="el" href="a00002.html" title="This type contains one value parsed from the CBOR stream. ">CborValue</a> object to JSON. 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 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 metadata 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 them.</dd></dl>
<dl class="section see"><dt>See Also</dt><dd><a class="el" href="a00019.html" title="Group of functions used to parse CBOR streams. ">Parsing CBOR streams</a>, <a class="el" href="a00020.html" title="Group of functions used to convert CBOR to text form. ">Converting CBOR to text</a>, <a class="el" href="a00019.html#gadb356bb705f2d8239f03b36081a43b4f" title="Initializes the CBOR parser for parsing size bytes beginning at buffer. ">cbor_parser_init()</a></dd></dl>
<h2 class="groupheader">Conversion limitations</h2>
<p>When converting from CBOR to JSON, there may be information loss. This section lists the possible scenarios.</p>
<dl class="section user"><dt>Number precision:</dt><dd>ALL JSON numbers, due to its JavaScript heritage, are IEEE 754 double-precision floating point. This means JSON is not capable of representing integers numbers outside the range [-(2<sup>53</sup>)+1, 2<sup>53</sup>-1] and is not capable of representing NaN or infinite. If the CBOR data contains a number outside the valid range, the conversion will lose precision. If the input was NaN or infinite, the result of the conversion will be "null". In addition, the distinction between half-, single- and double-precision is lost.</dd></dl>
<dl class="section user"><dt></dt><dd>If enabled, the original value and original type are stored in the metadata.</dd></dl>
<dl class="section user"><dt>Non-native types:</dt><dd>CBOR's type system is richer than JSON's, which means some data values cannot be represented when converted to JSON. The conversion silently turns them into strings: CBOR simple types become "simple(nn)" where <code>nn</code> is the simple type's value, with the exception of CBOR undefined, which becomes "undefined", while CBOR byte strings are converted to an Base16, Base64, or Base64url encoding</dd></dl>
<dl class="section user"><dt></dt><dd>If enabled, the original type is stored in the metadata.</dd></dl>
<dl class="section user"><dt>Presence of tags:</dt><dd>JSON has no support for tagged values, so by default tags are dropped when converting to JSON. However, if the CborConvertObeyByteStringTags option is active (default), then certain known tags are honored and are used to format the conversion of the tagged byte string to JSON.</dd></dl>
<dl class="section user"><dt></dt><dd>If the CborConvertTagsToObjects option is active, then the tag and the tagged value are converted to to a JSON object. Otherwise, if enabled, the last (innermost) tag is stored in the metadata.</dd></dl>
<dl class="section user"><dt>Non-string keys in maps:</dt><dd>JSON requires all Object keys to be strings, while CBOR does not. By default, if a non-string key is found, the conversion fails with error CborErrorJsonObjectKeyNotString. If the CborConvertStringifyMapKeys option is active, then the conversion attempts to create a string representation using CborPretty. Note that the <code>json2cbor</code> tool is not able to parse this back to the original form.</dd></dl>
<dl class="section user"><dt>Duplicate keys in maps:</dt><dd>Neither JSON nor CBOR allow duplicated keys, but current TinyCBOR does not validate that this is the case. If there are duplicated keys in the input, they will be repeated in the output, which may JSON tools may flag as invalid. In addition to that, if the CborConvertStringifyMapKeys option is active, it is possible that a non-string key in a CBOR map will be converted to a string form that is identical to another key.</dd></dl>
<dl class="section user"><dt></dt><dd>When metadata support is active, the conversion will add extra key-value pairs to the JSON output so it can store the metadata. It is possible that the keys for the metadata clash with existing keys in the JSON map. </dd></dl>
<h2 class="groupheader">Enumeration Type Documentation</h2>
<a class="anchor" id="ga2f7386ebce337e0de69cae456bda78f7"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">enum <a class="el" href="a00021.html#ga2f7386ebce337e0de69cae456bda78f7">CborToJsonFlags</a></td>
</tr>
</table>
</div><div class="memdoc">
<p>The CborToJsonFlags enum contains flags that control the conversion of CBOR to JSON. </p>
<ul>
<li><code>CborConvertAddMetadata</code> Adds metadata to facilitate restoration of the original CBOR data. </li>
<li><code>CborConvertTagsToObjects</code> Converts CBOR tags to JSON objects </li>
<li><code>CborConvertIgnoreTags</code> (default) Ignore CBOR tags, except for byte strings </li>
<li><code>CborConvertObeyByteStringTags</code> (default) Honor formatting of CBOR byte strings if so tagged </li>
<li><code>CborConvertByteStringsToBase64Url</code> Force the conversion of all CBOR byte strings to Base64url encoding, despite any tags </li>
<li><code>CborConvertRequireMapStringKeys</code> (default) Require CBOR map keys to be strings, failing the conversion if they are not </li>
<li><code>CborConvertStringifyMapKeys</code> Convert non-string keys in CBOR maps to a string form </li>
<li><code>CborConvertDefaultFlags</code> Default conversion flags. </li>
</ul>
</div>
</div>
<h2 class="groupheader">Function Documentation</h2>
<a class="anchor" id="ga3f2ce7eadf9a355654186166d24e69cf"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="a00017.html#ga76e9c9acc63dd940da4ab7e91309f7b5">CborError</a> cbor_value_to_json </td>
<td>(</td>
<td class="paramtype">FILE *&#160;</td>
<td class="paramname"><em>out</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const <a class="el" href="a00002.html">CborValue</a> *&#160;</td>
<td class="paramname"><em>value</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int&#160;</td>
<td class="paramname"><em>flags</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Converts the current CBOR type pointed by <em>value</em> to JSON and writes that to the <em>out</em> stream. </p>
<p>If an error occurs, this function returns an error code similar to CborParsing. The <em>flags</em> parameter indicates one of the flags from CborToJsonFlags that control the conversion.</p>
<dl class="section see"><dt>See Also</dt><dd><a class="el" href="a00021.html#ga558485bab0ebcb2646e7669d13861d79" title="Converts the current CBOR type pointed by value to JSON and writes that to the out stream...">cbor_value_to_json_advance()</a>, <a class="el" href="a00004.html#a0529f04ea9045bbd351ea03ee0a21b7b" title="Converts the current CBOR type pointed by value to its textual representation and writes it to the ou...">cbor_value_to_pretty()</a> </dd></dl>
</div>
</div>
<a class="anchor" id="ga558485bab0ebcb2646e7669d13861d79"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="a00017.html#ga76e9c9acc63dd940da4ab7e91309f7b5">CborError</a> cbor_value_to_json_advance </td>
<td>(</td>
<td class="paramtype">FILE *&#160;</td>
<td class="paramname"><em>out</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="a00002.html">CborValue</a> *&#160;</td>
<td class="paramname"><em>value</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int&#160;</td>
<td class="paramname"><em>flags</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Converts the current CBOR type pointed by <em>value</em> to JSON and writes that to the <em>out</em> stream. </p>
<p>If an error occurs, this function returns an error code similar to CborParsing. The <em>flags</em> parameter indicates one of the flags from CborToJsonFlags that control the conversion.</p>
<p>If no error ocurred, this function advances <em>value</em> to the next element.</p>
<dl class="section see"><dt>See Also</dt><dd><a class="el" href="a00021.html#ga3f2ce7eadf9a355654186166d24e69cf" title="Converts the current CBOR type pointed by value to JSON and writes that to the out stream...">cbor_value_to_json()</a>, <a class="el" href="a00004.html#aef4d5dc4b2bfaf458e82e350509f9c30" title="Converts the current CBOR type pointed by value to its textual representation and writes it to the ou...">cbor_value_to_pretty_advance()</a> </dd></dl>
<p>Referenced by <a class="el" href="a00021.html#ga3f2ce7eadf9a355654186166d24e69cf">cbor_value_to_json()</a>.</p>
</div>
</div>
</div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.6
</small></address>
</body>
</html>