<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html;charset=utf-8">
<meta http-equiv="cache-control" content="no-cache">
<title>Genivia - The WinInet plugin</title>
<link href="genivia_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">
<link href="genivia_content.css" rel="stylesheet" type="text/css">
</head>
<body>
<div id="top">
<div id="titlearea">
<table height="72px" width="100%" cellspacing="0" cellpadding="0">
<tbody>
<tr>
<td width="10%"> </td>
<td width="175px"><a href="https://www.genivia.com"><img alt="Genivia" src="GeniviaLogo2_trans_noslogan.png"/></a></td>
<td class="tab_home"><a href="https://www.genivia.com">Home</a></td>
<td class="tab_home"><a href="https://www.genivia.com/docs.html">Documentation</a></td>
<td>
<div style="float: right; font-size: 18px; font-weight: bold;">The WinInet plugin</div>
<br>
<div style="float: right; font-size: 10px;">updated Fri Jan 5 2018 by Robert van Engelen</div>
</td>
<td width="10%"> </td>
</tr>
</tbody>
</table>
</div>
<!-- Generated by Doxygen 1.8.11 -->
<div id="navrow1" class="tabs">
<ul class="tablist">
<li class="current"><a href="index.html"><span>Main Page</span></a></li>
<li><a href="annotated.html"><span>Classes</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
</div><!-- top -->
<div class="header">
<div class="headertitle">
<div class="title">The WinInet plugin </div> </div>
</div><!--header-->
<div class="contents">
<div class="toc"><h3>Table of Contents</h3>
<ul><li class="level1"><a href="#overview">Overview </a></li>
<li class="level1"><a href="#features">Features </a></li>
<li class="level1"><a href="#limitations">Limitations </a></li>
<li class="level1"><a href="#usage">Using the WinInet plugin with gSOAP </a></li>
<li class="level1"><a href="#options">WinInet plugin options </a></li>
<li class="level1"><a href="#license">License </a></li>
<li class="level1"><a href="#contributors">Contributors </a></li>
</ul>
</div>
<div class="textblock"><p>By Jack Kustanowitz, Brodie Thiesfield, and Robert van Engelen.</p>
<h1><a class="anchor" id="overview"></a>
Overview </h1>
<p>The WinInet plugin for gSOAP enables client applications (not servers) to communicate through Microsoft's WinInet API on Windows. This offers all of the advantages of WinInet-managed internet access through the <code>Internet Options</code> control panel of Windows, such as HTTP (proxy) authentication, TLS/SSL, and HTTP compression. Therefore, "if IE works, gSOAP works." since these options are shared by IE.</p>
<p>The WinInet project home is at <a href="http://code.google.com/p/gsoapwininet">http://code.google.com/p/gsoapwininet</a>.</p>
<p>This plugin is licensed differently than the other plugins for gSOAP. It is licensed under the <a href="#license">MIT license</a> and can be used with GPLv2 and the commercial license for gSOAP.</p>
<h1><a class="anchor" id="features"></a>
Features </h1>
<ul>
<li>A plugin for gSOAP that is very easy to use.</li>
<li>Complete support for HTTP features, including HTTPS, authentication (basic, digest, NTLM), proxy authentication</li>
<li>Authentication warnings (e.g. invalid TLS/SSL certificate) can be resolved by the user via standard system dialog boxes.</li>
<li>Timeouts for connect, receive, and send operations are obeyed when these are set BEFORE the plugin is registered with the engine.</li>
<li>Supports all <code>SOAP_IO</code> modes of gSOAP (see <a href="#limitations">limitations</a>).</li>
<li>Can be used with C, C++, and MFC projects.</li>
<li>Can be used in both MBCS and UNICODE projects.</li>
<li>Compiles cleanly at warning level 4 supporting Win32 and Win64.</li>
<li>Debug logging is supported (<code>TEST.log</code>, <code>SENT.log</code>, and <code>RECV.log</code>).</li>
<li>MT safe and supports multiple threads, as usual with gSOAP clients.</li>
</ul>
<h1><a class="anchor" id="limitations"></a>
Limitations </h1>
<ul>
<li>MIME and DIME attachments are not supported.</li>
<li>The plugin may internally buffer the entire outgoing message before sending, even when the <code>SOAP_IO_CHUNK</code> mode is used.</li>
<li>Because messages are buffered internally, do not use the <code>SOAP_IO_STORE</code> flag. Otherwise, the message may be buffered twice on every send.</li>
<li>This plugin uses the following callback functions and is not compatible with any other plugin that uses these functions: <code>soap::fopen</code>, <code>soap::fposthdr</code> <code>soap::fsend</code>, <code>soap::frecv</code>, <code>soap::fclose</code>.</li>
</ul>
<h1><a class="anchor" id="usage"></a>
Using the WinInet plugin with gSOAP </h1>
<p>Add the <code>gsoapWinInet2.h</code> and <code>gsoapWinInet2.cpp</code> files to your project. If you have a C project, change the extension to <code>.c</code>. Disable "precompiled headers" for the <code>.cpp</code> file.</p>
<p>In your source code for the client, register the WinInet plugin with <code>soap_register_plugin(soap, wininet_plugin)</code> after creation and initialization of the <code>soap</code> context.</p>
<p>For example, when using a proxy object in C++ generated with soapcpp2 -j:</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include "<a class="code" href="gsoap_win_inet_8h.html">gsoapWinInet.h</a>"</span></div><div class="line"><span class="preprocessor">#include "soapProxy.h"</span></div><div class="line">Proxy proxy;</div><div class="line">proxy.soap->connect_timeout = 15; <span class="comment">// 15 sec max connect time</span></div><div class="line">proxy.soap->recv_timeout = 10; <span class="comment">// 10 sec max recv time</span></div><div class="line">proxy.soap->send_timeout = 10; <span class="comment">// 10 sec max send time</span></div><div class="line">soap_register_plugin(proxy.soap, <a class="code" href="gsoap_win_inet_8cpp.html#ac6bca696008832fa8d798bc40766c122">wininet_plugin</a>);</div><div class="line">...</div><div class="line">proxy.destroy(); <span class="comment">// delete deserialized data</span></div></div><!-- fragment --><p>and in plain C/C++, that is, without a proxy object:</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include "soapH.h"</span></div><div class="line"><span class="preprocessor">#include "<a class="code" href="gsoap_win_inet_8h.html">gsoapWinInet.h</a>"</span></div><div class="line"><span class="keyword">struct </span>soap soap;</div><div class="line">soap_init(&soap);</div><div class="line">soap.connect_timeout = 15; <span class="comment">// 15 sec max connect time</span></div><div class="line">soap.recv_timeout = 10; <span class="comment">// 10 sec max recv time</span></div><div class="line">soap.send_timeout = 10; <span class="comment">// 10 sec max send time</span></div><div class="line">soap_register_plugin(&soap, <a class="code" href="gsoap_win_inet_8cpp.html#ac6bca696008832fa8d798bc40766c122">wininet_plugin</a>);</div><div class="line">...</div><div class="line">soap_destroy(&soap); <span class="comment">// delete deserialized data</span></div><div class="line">soap_end(&soap); <span class="comment">// delete temporary and C-based deserialized data</span></div><div class="line">soap_done(&soap);</div></div><!-- fragment --><p>Note that the receive and send timeouts limit the time to receive and send data, respectively. <b>This behavior differs from the gSOAP engine's timeouts that limit the socket receive and send operation idle times.</b> The gSOAP engine uses <code>transfer_timeout</code> to limit the receive and send times.</p>
<p>Please make sure to compile all sources in C++ compilation mode. If you migrate to a project file such as <code>.vcproj</code>, please set <code>CompileAs="2"</code> in your <code>.vcproj</code> file.</p>
<h1><a class="anchor" id="options"></a>
WinInet plugin options </h1>
<p>To control the WinInet's HttpOpenRequest options, register the WinInet plugin with <code>soap_register_plugin_arg()</code> and supply an argument that is passed on to HttpOpenRequest. For example:</p>
<div class="fragment"><div class="line">soap_register_plugin_arg(&soap, <a class="code" href="gsoap_win_inet_8cpp.html#ac6bca696008832fa8d798bc40766c122">wininet_plugin</a>, (<span class="keywordtype">void</span>*)INTERNET_FLAG_IGNORE_CERT_CN_INVALID);</div></div><!-- fragment --><p>See the MSDN documentation on HttpOpenRequest for details of the HttpOpenRequest flags. The <code>wininet.h</code> header must be included to use these flags.</p>
<ul>
<li><code>INTERNET_FLAG_KEEP_CONNECTION</code> use keep-alive semantics, if available, for the connection. This flag is required for Microsoft Network (MSN), NT LAN Manager (NTLM), and other types of authentication. This flag is set automatically when the soap context is initalized with <code>SOAP_IO_KEEPALIVE</code>.</li>
<li><code>INTERNET_FLAG_IGNORE_CERT_CN_INVALID</code> disables Microsoft Win32 Internet function checking of SSL/PCT- based certificates that are returned from the server against the host name given in the request.</li>
<li><code>INTERNET_FLAG_IGNORE_CERT_DATE_INVALID</code> disables Win32 Internet function checking of SSL/PCT-based certificates for proper validity dates.</li>
</ul>
<p>If there are errors in sending the HTTP request which would cause a dialog box to be displayed in IE (for instance, invalid certificates on an HTTPS connection), then a dialog will also be displayed by this library. At the moment is is not possible to disable the UI. If you wish to remove the UI then you will need to hack the source to remove the dialog box and resolve the errors programmatically, or supply the appropriate flags to <code>soap_register_plugin_arg()</code> to disable the unwanted warnings.</p>
<h1><a class="anchor" id="license"></a>
License </h1>
<p>The licence text below is the boilerplate "MIT Licence" used from: <a href="http://www.opensource.org/licenses/mit-license.php">http://www.opensource.org/licenses/mit-license.php</a></p>
<p>Copyright (c) 2009, Jack Kustanowitz, Brodie Thiesfield, Robert van Engelen</p>
<p>Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:</p>
<p>The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.</p>
<p>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.</p>
<h1><a class="anchor" id="contributors"></a>
Contributors </h1>
<ul>
<li>26 May 2003: Jack Kustanowitz (<a href="#" onclick="location.href='mai'+'lto:'+'jac'+'kk'+'@at'+'om'+'ica'+'.c'+'om'; return false;">jackk<span style="display: none;">.nosp@m.</span>@ato<span style="display: none;">.nosp@m.</span>mica.<span style="display: none;">.nosp@m.</span>com</a>): Original prototype version</li>
<li>29 September 2003: Brodie Thiesfield (<a href="#" onclick="location.href='mai'+'lto:'+'cod'+'e@'+'jel'+'ly'+'can'+'.c'+'om'; return false;">code@<span style="display: none;">.nosp@m.</span>jell<span style="display: none;">.nosp@m.</span>ycan.<span style="display: none;">.nosp@m.</span>com</a>): Rewritten as C plugin for gsoap. Bugs fixed and features added.</li>
<li>14 January 2004: Brodie Thiesfield (<a href="#" onclick="location.href='mai'+'lto:'+'cod'+'e@'+'jel'+'ly'+'can'+'.c'+'om'; return false;">code@<span style="display: none;">.nosp@m.</span>jell<span style="display: none;">.nosp@m.</span>ycan.<span style="display: none;">.nosp@m.</span>com</a>): Bug fix.</li>
<li>17 March 2009: Brodie Thiesfield (<a href="#" onclick="location.href='mai'+'lto:'+'cod'+'e@'+'jel'+'ly'+'can'+'.c'+'om'; return false;">code@<span style="display: none;">.nosp@m.</span>jell<span style="display: none;">.nosp@m.</span>ycan.<span style="display: none;">.nosp@m.</span>com</a>): Clean up and re-release.</li>
<li>8 October 2010: Robert van Engelen (<a href="#" onclick="location.href='mai'+'lto:'+'eng'+'el'+'en@'+'ge'+'niv'+'ia'+'.co'+'m'; return false;">engel<span style="display: none;">.nosp@m.</span>en@g<span style="display: none;">.nosp@m.</span>enivi<span style="display: none;">.nosp@m.</span>a.co<span style="display: none;">.nosp@m.</span>m</a>): Cleanup and bug fixes for error handling.</li>
<li>28 October 2015: Robert van Engelen (<a href="#" onclick="location.href='mai'+'lto:'+'eng'+'el'+'en@'+'ge'+'niv'+'ia'+'.co'+'m'; return false;">engel<span style="display: none;">.nosp@m.</span>en@g<span style="display: none;">.nosp@m.</span>enivi<span style="display: none;">.nosp@m.</span>a.co<span style="display: none;">.nosp@m.</span>m</a>): Plugin copy code added. </li>
</ul>
</div></div><!-- contents -->
<hr class="footer">
<address class="footer">
Copyright (C) 2018, Robert van Engelen, Genivia Inc., All Rights Reserved.
</address>
<address class="footer"><small>
Converted on Fri Jan 5 2018 11:21:49 by <a target="_blank" href="http://www.doxygen.org/index.html">Doxygen</a> 1.8.11</small></address>
<br>
<div style="height: 246px; background: #DBDBDB;">
</body>
</html>
