blob: cec553853f5f7f865abd898371aca75e2926efee [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.12"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>libwebsockets: Client</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="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="projectlogo"><img alt="Logo" src="libwebsockets.org-logo.png"/></td>
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">libwebsockets
</div>
<div id="projectbrief">Lightweight C library for HTML5 websockets</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.12 -->
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
$(function() {
initMenu('',false,false,'search.php','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__client.html','');});
</script>
<div id="doc-content">
<div class="header">
<div class="summary">
<a href="#nested-classes">Data Structures</a> &#124;
<a href="#enum-members">Enumerations</a> &#124;
<a href="#func-members">Functions</a> </div>
<div class="headertitle">
<div class="title">Client</div> </div>
</div><!--header-->
<div class="contents">
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="nested-classes"></a>
Data Structures</h2></td></tr>
<tr class="memitem:"><td class="memItemLeft" align="right" valign="top">struct &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="structlws__client__connect__info.html">lws_client_connect_info</a></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="enum-members"></a>
Enumerations</h2></td></tr>
<tr class="memitem:ga96f3dbad54b2853969cfa933d66871ce"><td class="memItemLeft" align="right" valign="top">enum &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__client.html#ga96f3dbad54b2853969cfa933d66871ce">lws_client_connect_ssl_connection_flags</a> { <b>LCCSCF_USE_SSL</b> = (1 &lt;&lt; 0),
<b>LCCSCF_ALLOW_SELFSIGNED</b> = (1 &lt;&lt; 1),
<b>LCCSCF_SKIP_SERVER_CERT_HOSTNAME_CHECK</b> = (1 &lt;&lt; 2),
<b>LCCSCF_ALLOW_EXPIRED</b> = (1 &lt;&lt; 3)
}</td></tr>
<tr class="separator:ga96f3dbad54b2853969cfa933d66871ce"><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:ga0c966136905f467816307cfba6deb5fd"><td class="memItemLeft" align="right" valign="top">LWS_VISIBLE LWS_EXTERN struct lws *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__client.html#ga0c966136905f467816307cfba6deb5fd">lws_client_connect_via_info</a> (struct <a class="el" href="structlws__client__connect__info.html">lws_client_connect_info</a> *ccinfo)</td></tr>
<tr class="separator:ga0c966136905f467816307cfba6deb5fd"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga4af0a20108a95e8b6d94dd4d80055ff3"><td class="memItemLeft" align="right" valign="top">LWS_VISIBLE LWS_EXTERN struct lws *LWS_WARN_UNUSED_RESULT&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__client.html#ga4af0a20108a95e8b6d94dd4d80055ff3">lws_client_connect</a> (struct lws_context *clients, const char *address, int port, int ssl_connection, const char *path, const char *host, const char *origin, const char *protocol, int ietf_version_or_minus_one) LWS_WARN_DEPRECATED</td></tr>
<tr class="separator:ga4af0a20108a95e8b6d94dd4d80055ff3"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:gac6a8558b4410961a880241c2ac1271e2"><td class="memItemLeft" align="right" valign="top">LWS_VISIBLE LWS_EXTERN struct lws *LWS_WARN_UNUSED_RESULT&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__client.html#gac6a8558b4410961a880241c2ac1271e2">lws_client_connect_extended</a> (struct lws_context *clients, const char *address, int port, int ssl_connection, const char *path, const char *host, const char *origin, const char *protocol, int ietf_version_or_minus_one, void *userdata) LWS_WARN_DEPRECATED</td></tr>
<tr class="separator:gac6a8558b4410961a880241c2ac1271e2"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga4f44b8230e6732816ca5cd8d1aaaf340"><td class="memItemLeft" align="right" valign="top">LWS_VISIBLE LWS_EXTERN int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__client.html#ga4f44b8230e6732816ca5cd8d1aaaf340">lws_init_vhost_client_ssl</a> (const struct <a class="el" href="structlws__context__creation__info.html">lws_context_creation_info</a> *info, struct lws_vhost *vhost)</td></tr>
<tr class="separator:ga4f44b8230e6732816ca5cd8d1aaaf340"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga4450c34200bf9dab3beb90ef23221870"><td class="memItemLeft" align="right" valign="top"><a id="ga4450c34200bf9dab3beb90ef23221870"></a>
LWS_VISIBLE LWS_EXTERN int&#160;</td><td class="memItemRight" valign="bottom"><b>lws_http_client_read</b> (struct lws *wsi, char **buf, int *len)</td></tr>
<tr class="separator:ga4450c34200bf9dab3beb90ef23221870"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga715efffc0c4e8fbf72a4293008eb2187"><td class="memItemLeft" align="right" valign="top">LWS_VISIBLE LWS_EXTERN unsigned int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__client.html#ga715efffc0c4e8fbf72a4293008eb2187">lws_http_client_http_response</a> (struct lws *wsi)</td></tr>
<tr class="separator:ga715efffc0c4e8fbf72a4293008eb2187"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga26588fb345083076c14169dd5859f57a"><td class="memItemLeft" align="right" valign="top"><a id="ga26588fb345083076c14169dd5859f57a"></a>
LWS_VISIBLE LWS_EXTERN void&#160;</td><td class="memItemRight" valign="bottom"><b>lws_client_http_body_pending</b> (struct lws *wsi, int something_left_to_send)</td></tr>
<tr class="separator:ga26588fb345083076c14169dd5859f57a"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table>
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
<h2>Client releated functions</h2>
<h2 class="groupheader">Enumeration Type Documentation</h2>
<a id="ga96f3dbad54b2853969cfa933d66871ce"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga96f3dbad54b2853969cfa933d66871ce">&sect;&nbsp;</a></span>lws_client_connect_ssl_connection_flags</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">enum <a class="el" href="group__client.html#ga96f3dbad54b2853969cfa933d66871ce">lws_client_connect_ssl_connection_flags</a></td>
</tr>
</table>
</div><div class="memdoc">
<p><code>#include &lt;<a class="el" href="libwebsockets_8h.html">lib/libwebsockets.h</a>&gt;</code></p>
<p>enum lws_client_connect_ssl_connection_flags - flags that may be used with struct <a class="el" href="structlws__client__connect__info.html">lws_client_connect_info</a> ssl_connection member to control if and how SSL checks apply to the client connection being created </p>
<div class="fragment"><div class="line"><a name="l01986"></a><span class="lineno"> 1986</span>&#160; {</div><div class="line"><a name="l01987"></a><span class="lineno"> 1987</span>&#160; LCCSCF_USE_SSL = (1 &lt;&lt; 0),</div><div class="line"><a name="l01988"></a><span class="lineno"> 1988</span>&#160; LCCSCF_ALLOW_SELFSIGNED = (1 &lt;&lt; 1),</div><div class="line"><a name="l01989"></a><span class="lineno"> 1989</span>&#160; LCCSCF_SKIP_SERVER_CERT_HOSTNAME_CHECK = (1 &lt;&lt; 2),</div><div class="line"><a name="l01990"></a><span class="lineno"> 1990</span>&#160; LCCSCF_ALLOW_EXPIRED = (1 &lt;&lt; 3)</div><div class="line"><a name="l01991"></a><span class="lineno"> 1991</span>&#160;};</div></div><!-- fragment -->
</div>
</div>
<h2 class="groupheader">Function Documentation</h2>
<a id="ga4af0a20108a95e8b6d94dd4d80055ff3"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga4af0a20108a95e8b6d94dd4d80055ff3">&sect;&nbsp;</a></span>lws_client_connect()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">LWS_VISIBLE LWS_EXTERN struct lws* LWS_WARN_UNUSED_RESULT lws_client_connect </td>
<td>(</td>
<td class="paramtype">struct lws_context *&#160;</td>
<td class="paramname"><em>clients</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char *&#160;</td>
<td class="paramname"><em>address</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int&#160;</td>
<td class="paramname"><em>port</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int&#160;</td>
<td class="paramname"><em>ssl_connection</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char *&#160;</td>
<td class="paramname"><em>path</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char *&#160;</td>
<td class="paramname"><em>host</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char *&#160;</td>
<td class="paramname"><em>origin</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char *&#160;</td>
<td class="paramname"><em>protocol</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int&#160;</td>
<td class="paramname"><em>ietf_version_or_minus_one</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p><code>#include &lt;<a class="el" href="libwebsockets_8h.html">lib/libwebsockets.h</a>&gt;</code></p>
<p><a class="el" href="group__client.html#ga4af0a20108a95e8b6d94dd4d80055ff3">lws_client_connect()</a> - Connect to another websocket server </p><dl class="deprecated"><dt><b><a class="el" href="deprecated.html#_deprecated000002">Deprecated:</a></b></dt><dd>DEPRECATED use lws_client_connect_via_info </dd></dl>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">clients</td><td>Websocket context </td></tr>
<tr><td class="paramname">address</td><td>Remote server address, eg, "myserver.com" </td></tr>
<tr><td class="paramname">port</td><td>Port to connect to on the remote server, eg, 80 </td></tr>
<tr><td class="paramname">ssl_connection</td><td>0 = ws://, 1 = wss:// encrypted, 2 = wss:// allow self signed certs </td></tr>
<tr><td class="paramname">path</td><td>Websocket path on server </td></tr>
<tr><td class="paramname">host</td><td>Hostname on server </td></tr>
<tr><td class="paramname">origin</td><td>Socket origin name </td></tr>
<tr><td class="paramname">protocol</td><td>Comma-separated list of protocols being asked for from the server, or just one. The server will pick the one it likes best. If you don't want to specify a protocol, which is legal, use NULL here. </td></tr>
<tr><td class="paramname">ietf_version_or_minus_one</td><td>-1 to ask to connect using the default, latest protocol supported, or the specific protocol ordinal</td></tr>
</table>
</dd>
</dl>
<p>This function creates a connection to a remote server </p>
</div>
</div>
<a id="gac6a8558b4410961a880241c2ac1271e2"></a>
<h2 class="memtitle"><span class="permalink"><a href="#gac6a8558b4410961a880241c2ac1271e2">&sect;&nbsp;</a></span>lws_client_connect_extended()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">LWS_VISIBLE LWS_EXTERN struct lws* LWS_WARN_UNUSED_RESULT lws_client_connect_extended </td>
<td>(</td>
<td class="paramtype">struct lws_context *&#160;</td>
<td class="paramname"><em>clients</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char *&#160;</td>
<td class="paramname"><em>address</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int&#160;</td>
<td class="paramname"><em>port</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int&#160;</td>
<td class="paramname"><em>ssl_connection</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char *&#160;</td>
<td class="paramname"><em>path</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char *&#160;</td>
<td class="paramname"><em>host</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char *&#160;</td>
<td class="paramname"><em>origin</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char *&#160;</td>
<td class="paramname"><em>protocol</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int&#160;</td>
<td class="paramname"><em>ietf_version_or_minus_one</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">void *&#160;</td>
<td class="paramname"><em>userdata</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p><code>#include &lt;<a class="el" href="libwebsockets_8h.html">lib/libwebsockets.h</a>&gt;</code></p>
<p><a class="el" href="group__client.html#gac6a8558b4410961a880241c2ac1271e2">lws_client_connect_extended()</a> - Connect to another websocket server </p><dl class="deprecated"><dt><b><a class="el" href="deprecated.html#_deprecated000003">Deprecated:</a></b></dt><dd>DEPRECATED use lws_client_connect_via_info </dd></dl>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">clients</td><td>Websocket context </td></tr>
<tr><td class="paramname">address</td><td>Remote server address, eg, "myserver.com" </td></tr>
<tr><td class="paramname">port</td><td>Port to connect to on the remote server, eg, 80 </td></tr>
<tr><td class="paramname">ssl_connection</td><td>0 = ws://, 1 = wss:// encrypted, 2 = wss:// allow self signed certs </td></tr>
<tr><td class="paramname">path</td><td>Websocket path on server </td></tr>
<tr><td class="paramname">host</td><td>Hostname on server </td></tr>
<tr><td class="paramname">origin</td><td>Socket origin name </td></tr>
<tr><td class="paramname">protocol</td><td>Comma-separated list of protocols being asked for from the server, or just one. The server will pick the one it likes best. </td></tr>
<tr><td class="paramname">ietf_version_or_minus_one</td><td>-1 to ask to connect using the default, latest protocol supported, or the specific protocol ordinal </td></tr>
<tr><td class="paramname">userdata</td><td>Pre-allocated user data <pre class="fragment"> This function creates a connection to a remote server</pre> </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a id="ga0c966136905f467816307cfba6deb5fd"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga0c966136905f467816307cfba6deb5fd">&sect;&nbsp;</a></span>lws_client_connect_via_info()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">LWS_VISIBLE LWS_EXTERN struct lws* lws_client_connect_via_info </td>
<td>(</td>
<td class="paramtype">struct <a class="el" href="structlws__client__connect__info.html">lws_client_connect_info</a> *&#160;</td>
<td class="paramname"><em>ccinfo</em></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p><code>#include &lt;<a class="el" href="libwebsockets_8h.html">lib/libwebsockets.h</a>&gt;</code></p>
<p><a class="el" href="group__client.html#ga0c966136905f467816307cfba6deb5fd">lws_client_connect_via_info()</a> - Connect to another websocket server </p><dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">ccinfo</td><td>pointer to <a class="el" href="structlws__client__connect__info.html">lws_client_connect_info</a> struct <pre class="fragment"> This function creates a connection to a remote server using the
information provided in ccinfo.</pre> </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a id="ga715efffc0c4e8fbf72a4293008eb2187"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga715efffc0c4e8fbf72a4293008eb2187">&sect;&nbsp;</a></span>lws_http_client_http_response()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">LWS_VISIBLE LWS_EXTERN unsigned int lws_http_client_http_response </td>
<td>(</td>
<td class="paramtype">struct lws *&#160;</td>
<td class="paramname"><em>wsi</em></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p><code>#include &lt;<a class="el" href="libwebsockets_8h.html">lib/libwebsockets.h</a>&gt;</code></p>
<p><a class="el" href="group__client.html#ga715efffc0c4e8fbf72a4293008eb2187">lws_http_client_http_response()</a> - get last HTTP response code</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">wsi</td><td>client connection</td></tr>
</table>
</dd>
</dl>
<p>Returns the last server response code, eg, 200 for client http connections. </p>
</div>
</div>
<a id="ga4f44b8230e6732816ca5cd8d1aaaf340"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga4f44b8230e6732816ca5cd8d1aaaf340">&sect;&nbsp;</a></span>lws_init_vhost_client_ssl()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">LWS_VISIBLE LWS_EXTERN int lws_init_vhost_client_ssl </td>
<td>(</td>
<td class="paramtype">const struct <a class="el" href="structlws__context__creation__info.html">lws_context_creation_info</a> *&#160;</td>
<td class="paramname"><em>info</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">struct lws_vhost *&#160;</td>
<td class="paramname"><em>vhost</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p><code>#include &lt;<a class="el" href="libwebsockets_8h.html">lib/libwebsockets.h</a>&gt;</code></p>
<p><a class="el" href="group__client.html#ga4f44b8230e6732816ca5cd8d1aaaf340">lws_init_vhost_client_ssl()</a> - also enable client SSL on an existing vhost</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">info</td><td>client ssl related info </td></tr>
<tr><td class="paramname">vhost</td><td>which vhost to initialize client ssl operations on</td></tr>
</table>
</dd>
</dl>
<p>You only need to call this if you plan on using SSL client connections on the vhost. For non-SSL client connections, it's not necessary to call this.</p>
<p>The following members of info are used during the call </p><pre class="fragment"> - options must have LWS_SERVER_OPTION_DO_SSL_GLOBAL_INIT set,
otherwise the call does nothing
- provided_client_ssl_ctx must be NULL to get a generated client
ssl context, otherwise you can pass a prepared one in by setting it
- ssl_cipher_list may be NULL or set to the client valid cipher list
- ssl_ca_filepath may be NULL or client cert filepath
- ssl_cert_filepath may be NULL or client cert filepath
- ssl_private_key_filepath may be NULL or client cert private key
</pre><p>You must create your vhost explicitly if you want to use this, so you have a pointer to the vhost. Create the context first with the option flag LWS_SERVER_OPTION_EXPLICIT_VHOSTS and then call <a class="el" href="group__context-and-vhost.html#ga0c54c667ccd9b8b3dddcd123ca72f87c">lws_create_vhost()</a> with the same info struct. </p>
</div>
</div>
</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.12 </li>
</ul>
</div>
</body>
</html>