doc/doxygen/output/html/group__altcp__api.html - third_party/github/STMicroelectronics/stm32_mw_lwip - Git at Google

 <!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.13"/>
 <meta name="viewport" content="width=device-width, initial-scale=1"/>
 <title>lwIP: Application layered TCP Introduction</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="navtree.css" rel="stylesheet" type="text/css"/>
 <script type="text/javascript" src="resize.js"></script>
 <script type="text/javascript" src="navtreedata.js"></script>
 <script type="text/javascript" src="navtree.js"></script>
 <script type="text/javascript">
   $(document).ready(initResizable);
 </script>
 <link href="search/search.css" rel="stylesheet" type="text/css"/>
 <script type="text/javascript" src="search/searchdata.js"></script>
 <script type="text/javascript" src="search/search.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 id="projectalign" style="padding-left: 0.5em;">
    <div id="projectname">lwIP
    &#160;<span id="projectnumber">2.1.2</span>
    </div>
    <div id="projectbrief">Lightweight IP stack</div>
   </td>
  </tr>
  </tbody>
 </table>
 </div>
 <!-- end header part -->
 <!-- Generated by Doxygen 1.8.13 -->
 <script type="text/javascript">
 var searchBox = new SearchBox("searchBox", "search",false,'Search');
 </script>
 <script type="text/javascript" src="menudata.js"></script>
 <script type="text/javascript" src="menu.js"></script>
 <script type="text/javascript">
 $(function() {
   initMenu('',true,false,'search.php','Search');
   $(document).ready(function() { init_search(); });
 });
 </script>
 <div id="main-nav"></div>
 </div><!-- top -->
 <div id="side-nav" class="ui-resizable side-nav-resizable">
   <div id="nav-tree">
     <div id="nav-tree-contents">
       <div id="nav-sync" class="sync"></div>
     </div>
   </div>
   <div id="splitbar" style="-moz-user-select:none;"
        class="ui-resizable-handle">
   </div>
 </div>
 <script type="text/javascript">
 $(document).ready(function(){initNavTree('group__altcp__api.html','');});
 </script>
 <div id="doc-content">
 <!-- window showing the filter options -->
 <div id="MSearchSelectWindow"
      onmouseover="return searchBox.OnSearchSelectShow()"
      onmouseout="return searchBox.OnSearchSelectHide()"
      onkeydown="return searchBox.OnSearchSelectKey(event)">
 </div>

 <!-- iframe showing the search results (closed by default) -->
 <div id="MSearchResultsWindow">
 <iframe src="javascript:void(0)" frameborder="0"
         name="MSearchResults" id="MSearchResults">
 </iframe>
 </div>

 <div class="header">
   <div class="summary">
 <a href="#groups">Modules</a>  </div>
   <div class="headertitle">
 <div class="title">Application layered TCP Introduction<div class="ingroups"><a class="el" href="group__api.html">APIs</a> &raquo; <a class="el" href="group__callbackstyle__api.html">&quot;raw&quot; APIs</a></div></div>  </div>
 </div><!--header-->
 <div class="contents">
 <table class="memberdecls">
 <tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="groups"></a>
 Modules</h2></td></tr>
 <tr class="memitem:group__altcp"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__altcp.html">Application layered TCP Functions</a></td></tr>
 <tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
 </table>
 <a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
 <h2>Overview </h2>
 <p>altcp (application layered TCP connection API; to be used from TCPIP thread) is an abstraction layer that prevents applications linking hard against the <a class="el" href="tcp_8h.html">tcp.h</a> functions while providing the same functionality. It is used to e.g. add SSL/TLS (see LWIP_ALTCP_TLS) or proxy-connect support to an application written for the tcp callback API without that application knowing the protocol details.</p>
 <ul>
 <li>This interface mimics the tcp callback API to the application while preventing direct linking (much like virtual functions).</li>
 <li>This way, an application can make use of other application layer protocols on top of TCP without knowing the details (e.g. TLS, proxy connection).</li>
 <li>This is achieved by simply including "lwip/altcp.h" instead of "lwip/tcp.h", replacing "struct tcp_pcb" with "struct altcp_pcb" and prefixing all functions with "altcp_" instead of "tcp_".</li>
 </ul>
 <p>With altcp support disabled (LWIP_ALTCP==0), applications written against the altcp API can still be compiled but are directly linked against the tcp.h callback API and then cannot use layered protocols. To minimize code changes in this case, the use of altcp_allocators is strongly suggested.</p>
 <h2>Usage </h2>
 <p>To make use of this API from an existing tcp raw API application:</p><ul>
 <li>Include "lwip/altcp.h" instead of "lwip/tcp.h"</li>
 <li>Replace "struct tcp_pcb" with "struct altcp_pcb"</li>
 <li>Prefix all called tcp API functions with "altcp_" instead of "tcp_" to link against the altcp functions</li>
 <li><a class="el" href="group__altcp.html#ga86843287b0ad0099c067817cfb7aa336">altcp_new</a> (and <a class="el" href="group__altcp.html#gab631f6f92d7f6c58d9db27b7b415bc21">altcp_new_ip_type</a>/<a class="el" href="group__altcp.html#gaa51a47bcb334b188c82a1b99db49f1f1">altcp_new_ip6</a>) take an <a class="el" href="group__altcp.html#ga9ddf490e24b1472a96ab2b4cedd171f8">altcp_allocator_t</a> as an argument, whereas the original tcp API functions take no arguments.</li>
 <li>An <a class="el" href="group__altcp.html#ga9ddf490e24b1472a96ab2b4cedd171f8">altcp_allocator_t</a> allocator is an object that holds a pointer to an allocator object and a corresponding state (e.g. for TLS, the corresponding state may hold certificates or keys). This way, the application does not even need to know if it uses TLS or pure TCP, this is handled at runtime by passing a specific allocator.</li>
 <li>An application can alternatively bind hard to the altcp_tls API by calling <a class="el" href="group__altcp__tls.html#ga028316a8257cf8dcace9cd063de79c0a">altcp_tls_new</a> or <a class="el" href="group__altcp__tls.html#gab874adb7f87984c0520bd032c2108c47">altcp_tls_wrap</a>.</li>
 <li>The TLS layer is not directly implemented by lwIP, but a port to mbedTLS is provided.</li>
 <li>Another altcp layer is proxy-connect to use TLS behind a HTTP proxy (see <a class="el" href="altcp__proxyconnect_8h.html">altcp_proxyconnect.h</a>)</li>
 </ul>
 <h2>altcp_allocator_t </h2>
 <p>An altcp allocator is created by the application by combining an allocator callback function and a corresponding state, e.g.:</p><div class="fragment"><div class="line"><span class="keyword">static</span> <span class="keyword">const</span> <span class="keywordtype">unsigned</span> <span class="keywordtype">char</span> cert[] = {0x2D, ... (see mbedTLS doc <span class="keywordflow">for</span> how to create <span class="keyword">this</span>)};</div><div class="line"><span class="keyword">struct </span>altcp_tls_config * conf = <a class="code" href="group__altcp__tls.html#ga2b249447e10c8599b6d723d403086c35">altcp_tls_create_config_client</a>(cert, <span class="keyword">sizeof</span>(cert));</div><div class="line"><a class="code" href="structaltcp__allocator__s.html">altcp_allocator_t</a> tls_allocator = {</div><div class="line">  <a class="code" href="group__altcp__tls.html#ga09e6ca8f144ee94ef21d7e5760aa4391">altcp_tls_alloc</a>, conf</div><div class="line">};</div></div><!-- fragment --><h2>struct altcp_tls_config </h2>
 <p>The struct altcp_tls_config holds state that is needed to create new TLS client or server connections (e.g. certificates and private keys).</p>
 <p>It is not defined by lwIP itself but by the TLS port (e.g. altcp_tls to mbedTLS adaption). However, the parameters used to create it are defined in <a class="el" href="altcp__tls_8h.html">altcp_tls.h</a> (see <a class="el" href="group__altcp__tls.html#ga700dc0320e93cea337673e7d4295e161">altcp_tls_create_config_server_privkey_cert</a> for servers and <a class="el" href="group__altcp__tls.html#ga2b249447e10c8599b6d723d403086c35">altcp_tls_create_config_client</a>/<a class="el" href="group__altcp__tls.html#ga7352a4600fee89e167541cf0776c01fb">altcp_tls_create_config_client_2wayauth</a> for clients).</p>
 <p>For mbedTLS, ensure that certificates can be parsed by 'mbedtls_x509_crt_parse()' and private keys can be parsed by 'mbedtls_pk_parse_key()'. </p>
 </div><!-- contents -->
 </div><!-- doc-content -->
 <!-- start footer part -->
 <div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
   <ul>
     <li class="footer">Generated by
     <a href="http://www.doxygen.org/index.html">
     <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.13 </li>
   </ul>
 </div>
 </body>
 </html>
	<!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.13"/>
	<meta name="viewport" content="width=device-width, initial-scale=1"/>
	<title>lwIP: Application layered TCP Introduction</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="navtree.css" rel="stylesheet" type="text/css"/>
	<script type="text/javascript" src="resize.js"></script>
	<script type="text/javascript" src="navtreedata.js"></script>
	<script type="text/javascript" src="navtree.js"></script>
	<script type="text/javascript">
	$(document).ready(initResizable);
	</script>
	<link href="search/search.css" rel="stylesheet" type="text/css"/>
	<script type="text/javascript" src="search/searchdata.js"></script>
	<script type="text/javascript" src="search/search.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 id="projectalign" style="padding-left: 0.5em;">
	<div id="projectname">lwIP
	<span id="projectnumber">2.1.2</span>
	</div>
	<div id="projectbrief">Lightweight IP stack</div>
	</td>
	</tr>
	</tbody>
	</table>
	</div>
	<!-- end header part -->
	<!-- Generated by Doxygen 1.8.13 -->
	<script type="text/javascript">
	var searchBox = new SearchBox("searchBox", "search",false,'Search');
	</script>
	<script type="text/javascript" src="menudata.js"></script>
	<script type="text/javascript" src="menu.js"></script>
	<script type="text/javascript">
	$(function() {
	initMenu('',true,false,'search.php','Search');
	$(document).ready(function() { init_search(); });
	});
	</script>
	<div id="main-nav"></div>
	</div><!-- top -->
	<div id="side-nav" class="ui-resizable side-nav-resizable">
	<div id="nav-tree">
	<div id="nav-tree-contents">
	<div id="nav-sync" class="sync"></div>
	</div>
	</div>
	<div id="splitbar" style="-moz-user-select:none;"
	class="ui-resizable-handle">
	</div>
	</div>
	<script type="text/javascript">
	$(document).ready(function(){initNavTree('group__altcp__api.html','');});
	</script>
	<div id="doc-content">
	<!-- window showing the filter options -->
	<div id="MSearchSelectWindow"
	onmouseover="return searchBox.OnSearchSelectShow()"
	onmouseout="return searchBox.OnSearchSelectHide()"
	onkeydown="return searchBox.OnSearchSelectKey(event)">
	</div>

	<!-- iframe showing the search results (closed by default) -->
	<div id="MSearchResultsWindow">
	<iframe src="javascript:void(0)" frameborder="0"
	name="MSearchResults" id="MSearchResults">
	</iframe>
	</div>

	<div class="header">
	<div class="summary">
	<a href="#groups">Modules</a> </div>
	<div class="headertitle">
	<div class="title">Application layered TCP Introduction<div class="ingroups"><a class="el" href="group__api.html">APIs</a> » <a class="el" href="group__callbackstyle__api.html">"raw" APIs</a></div></div> </div>
	</div><!--header-->
	<div class="contents">
	<table class="memberdecls">
	<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="groups"></a>
	Modules</h2></td></tr>
	<tr class="memitem:group__altcp"><td class="memItemLeft" align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="group__altcp.html">Application layered TCP Functions</a></td></tr>
	<tr class="separator:"><td class="memSeparator" colspan="2"> </td></tr>
	</table>
	<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
	<h2>Overview </h2>
	<p>altcp (application layered TCP connection API; to be used from TCPIP thread) is an abstraction layer that prevents applications linking hard against the <a class="el" href="tcp_8h.html">tcp.h</a> functions while providing the same functionality. It is used to e.g. add SSL/TLS (see LWIP_ALTCP_TLS) or proxy-connect support to an application written for the tcp callback API without that application knowing the protocol details.</p>
	<ul>
	<li>This interface mimics the tcp callback API to the application while preventing direct linking (much like virtual functions).</li>
	<li>This way, an application can make use of other application layer protocols on top of TCP without knowing the details (e.g. TLS, proxy connection).</li>
	<li>This is achieved by simply including "lwip/altcp.h" instead of "lwip/tcp.h", replacing "struct tcp_pcb" with "struct altcp_pcb" and prefixing all functions with "altcp_" instead of "tcp_".</li>
	</ul>
	<p>With altcp support disabled (LWIP_ALTCP==0), applications written against the altcp API can still be compiled but are directly linked against the tcp.h callback API and then cannot use layered protocols. To minimize code changes in this case, the use of altcp_allocators is strongly suggested.</p>
	<h2>Usage </h2>
	<p>To make use of this API from an existing tcp raw API application:</p><ul>
	<li>Include "lwip/altcp.h" instead of "lwip/tcp.h"</li>
	<li>Replace "struct tcp_pcb" with "struct altcp_pcb"</li>
	<li>Prefix all called tcp API functions with "altcp_" instead of "tcp_" to link against the altcp functions</li>
	<li><a class="el" href="group__altcp.html#ga86843287b0ad0099c067817cfb7aa336">altcp_new</a> (and <a class="el" href="group__altcp.html#gab631f6f92d7f6c58d9db27b7b415bc21">altcp_new_ip_type</a>/<a class="el" href="group__altcp.html#gaa51a47bcb334b188c82a1b99db49f1f1">altcp_new_ip6</a>) take an <a class="el" href="group__altcp.html#ga9ddf490e24b1472a96ab2b4cedd171f8">altcp_allocator_t</a> as an argument, whereas the original tcp API functions take no arguments.</li>
	<li>An <a class="el" href="group__altcp.html#ga9ddf490e24b1472a96ab2b4cedd171f8">altcp_allocator_t</a> allocator is an object that holds a pointer to an allocator object and a corresponding state (e.g. for TLS, the corresponding state may hold certificates or keys). This way, the application does not even need to know if it uses TLS or pure TCP, this is handled at runtime by passing a specific allocator.</li>
	<li>An application can alternatively bind hard to the altcp_tls API by calling <a class="el" href="group__altcp__tls.html#ga028316a8257cf8dcace9cd063de79c0a">altcp_tls_new</a> or <a class="el" href="group__altcp__tls.html#gab874adb7f87984c0520bd032c2108c47">altcp_tls_wrap</a>.</li>
	<li>The TLS layer is not directly implemented by lwIP, but a port to mbedTLS is provided.</li>
	<li>Another altcp layer is proxy-connect to use TLS behind a HTTP proxy (see <a class="el" href="altcp__proxyconnect_8h.html">altcp_proxyconnect.h</a>)</li>
	</ul>
	<h2>altcp_allocator_t </h2>
	<p>An altcp allocator is created by the application by combining an allocator callback function and a corresponding state, e.g.:</p><div class="fragment"><div class="line"><span class="keyword">static</span> <span class="keyword">const</span> <span class="keywordtype">unsigned</span> <span class="keywordtype">char</span> cert[] = {0x2D, ... (see mbedTLS doc <span class="keywordflow">for</span> how to create <span class="keyword">this</span>)};</div><div class="line"><span class="keyword">struct </span>altcp_tls_config * conf = <a class="code" href="group__altcp__tls.html#ga2b249447e10c8599b6d723d403086c35">altcp_tls_create_config_client</a>(cert, <span class="keyword">sizeof</span>(cert));</div><div class="line"><a class="code" href="structaltcp__allocator__s.html">altcp_allocator_t</a> tls_allocator = {</div><div class="line"> <a class="code" href="group__altcp__tls.html#ga09e6ca8f144ee94ef21d7e5760aa4391">altcp_tls_alloc</a>, conf</div><div class="line">};</div></div><!-- fragment --><h2>struct altcp_tls_config </h2>
	<p>The struct altcp_tls_config holds state that is needed to create new TLS client or server connections (e.g. certificates and private keys).</p>
	<p>It is not defined by lwIP itself but by the TLS port (e.g. altcp_tls to mbedTLS adaption). However, the parameters used to create it are defined in <a class="el" href="altcp__tls_8h.html">altcp_tls.h</a> (see <a class="el" href="group__altcp__tls.html#ga700dc0320e93cea337673e7d4295e161">altcp_tls_create_config_server_privkey_cert</a> for servers and <a class="el" href="group__altcp__tls.html#ga2b249447e10c8599b6d723d403086c35">altcp_tls_create_config_client</a>/<a class="el" href="group__altcp__tls.html#ga7352a4600fee89e167541cf0776c01fb">altcp_tls_create_config_client_2wayauth</a> for clients).</p>
	<p>For mbedTLS, ensure that certificates can be parsed by 'mbedtls_x509_crt_parse()' and private keys can be parsed by 'mbedtls_pk_parse_key()'. </p>
	</div><!-- contents -->
	</div><!-- doc-content -->
	<!-- start footer part -->
	<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
	<ul>
	<li class="footer">Generated by
	<a href="http://www.doxygen.org/index.html">
	<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.13 </li>
	</ul>
	</div>
	</body>
	</html>