ext/CrashServer/external/gsoap-win32-2.8.0/mod_gsoap/gsoap_win/wininet/gsoapWinInet.h

   1 /*
   2 ===============================================================================
   3 GSOAP WININET PLUGIN
   4 -------------------------------------------------------------------------------
   5
   6 Allow gsoap clients (not servers) to direct all communications through the
   7 WinInet API. This automatically provides all of the proxy and authentication
   8 features supported by the control panel 'Internet Options' dialog to the
   9 client. As these options are shared by IE, this means that "if IE works,
  10 gsoap works."
  11
  12 Project Home: http://code.google.com/p/gsoapwininet/
  13
  14 -------------------------------------------------------------------------------
  15 Features
  16 -------------------------------------------------------------------------------
  17
  18  + gsoap plugin - extremely easy to use
  19  + complete support for:
  20      - HTTP/1.0 and HTTP/1.1
  21      - HTTPS (no extra libraries are required)
  22      - HTTP authentication
  23      - Proxy servers (simple, automatic discovery, etc)
  24      - Proxy authentication (basic, NTLM, etc)
  25  + authentication prompts and HTTPS warnings (e.g. invalid HTTPS CA)
  26      can be resolved by the user via standard system dialog boxes.
  27  + message size is limited only by available memory
  28  + connect, receive and send timeouts are used
  29  + supports all SOAP_IO types (see limitations)
  30  + written completely in C, can be used in C, C++, and MFC projects
  31      without modification (anywhere that gsoap is used)
  32  + can be used in both MBCS and UNICODE projects
  33  + compiles cleanly at warning level 4 (if gsoap uses SOAP_SOCKET
  34      for the definition of sockets instead of int, it will also
  35      compile without win64 warnings).
  36  + all debug trace goes to the gsoap TEST.log file
  37  + supports multiple threads (all plugin data is stored in the
  38      soap structure - no static variables)
  39
  40 -------------------------------------------------------------------------------
  41 Limitations
  42 -------------------------------------------------------------------------------
  43  - DIME attachments are not supported
  44  - may internally buffer the entire outgoing message before sending
  45      (if the serialized message is larger then SOAP_BUFLEN, or if
  46      SOAP_IO_CHUNK mode is being used then the entire message will
  47      be buffered)
  48
  49 -------------------------------------------------------------------------------
  50 Usage
  51 -------------------------------------------------------------------------------
  52
  53 Add the gsoapWinInet2.h and gsoapWinInet2.cpp files to your project (if you
  54 have a C project, rename gsoapWinInet2.cpp to .c and use it as is). Ensure
  55 that you turn off precompiled headers for the .cpp file.
  56
  57 In your source, just after calling soap_init(), register this plugin with
  58 soap_register_plugin( soap, wininet_plugin ).
  59
  60 For example:
  61      struct soap soap;
  62      soap_init( &soap );
  63      soap_register_plugin( &soap, wininet_plugin );
  64      soap.connect_timeout = 5; // this will be used by wininet too
  65      ...
  66      soap_done(&soap);
  67
  68 -------------------------------------------------------------------------------
  69 Notes
  70 -------------------------------------------------------------------------------
  71
  72 For extra control, you may also register this plugin using the
  73 soap_register_plugin_arg() function, and supply as the argument flags which
  74 you want to be passed to HttpOpenRequest.
  75
  76 For example:
  77      struct soap soap;
  78      soap_init( &soap );
  79      soap_register_plugin_arg( &soap, wininet_plugin,
  80          (void*) INTERNET_FLAG_IGNORE_CERT_CN_INVALID );
  81
  82 See the MSDN documentation on HttpOpenRequest for details of available flags.
  83 The <wininet.h> header file is required for the definitions of the flags.
  84 Some flags which may be useful are:
  85
  86 INTERNET_FLAG_KEEP_CONNECTION
  87
  88      Uses keep-alive semantics, if available, for the connection.
  89      This flag is required for Microsoft Network (MSN), NT LAN
  90      Manager (NTLM), and other types of authentication.
  91      ++ Note that this flag is used automatically when soap.omode
  92      has the SOAP_IO_KEEPALIVE flag set. ++
  93
  94 INTERNET_FLAG_IGNORE_CERT_CN_INVALID
  95
  96      Disables Microsoft Win32 Internet function checking of SSL/PCT-
  97      based certificates that are returned from the server against
  98      the host name given in the request.
  99
 100 INTERNET_FLAG_IGNORE_CERT_DATE_INVALID
 101
 102      Disables Win32 Internet function checking of SSL/PCT-based
 103      certificates for proper validity dates.
 104
 105 This plugin uses the following callback functions and is not compatible
 106 with any other plugin that uses these functions.
 107
 108      soap->fopen
 109      soap->fposthdr
 110      soap->fsend
 111      soap->frecv
 112      soap->fclose
 113
 114 If there are errors in sending the HTTP request which would cause a dialog
 115 box to be displayed in IE (for instance, invalid certificates on an HTTPS
 116 connection), then a dialog will also be displayed by this library. At the
 117 moment is is not possible to disable the UI. If you wish to remove the UI
 118 then you will need to hack the source to remove the dialog box and resolve the
 119 errors programmatically, or supply the appropriate flags in
 120 soap_register_plugin_arg() to disable the unwanted warnings.
 121
 122 Because messages are buffered internally to gsoapWinInet2 plugin it is
 123 recommended that the SOAP_IO_STORE flag is not used otherwise the message may
 124 be buffered twice on every send. Use the default flag SOAP_IO_BUFFER,
 125 or SOAP_IO_FLUSH.
 126
 127 -------------------------------------------------------------------------------
 128 License
 129 -------------------------------------------------------------------------------
 130
 131 The licence text below is the boilerplate "MIT Licence" used from:
 132 http://www.opensource.org/licenses/mit-license.php
 133
 134 Copyright (c) 2009, Brodie Thiesfield
 135
 136 Permission is hereby granted, free of charge, to any person obtaining a copy
 137 of this software and associated documentation files (the "Software"), to deal
 138 in the Software without restriction, including without limitation the rights
 139 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 140 copies of the Software, and to permit persons to whom the Software is furnished
 141 to do so, subject to the following conditions:
 142
 143 The above copyright notice and this permission notice shall be included in
 144 all copies or substantial portions of the Software.
 145
 146 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 147 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
 148 FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
 149 COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
 150 IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
 151 CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 152
 153 -------------------------------------------------------------------------------
 154 Developers
 155 -------------------------------------------------------------------------------
 156
 157 26 May 2003: Jack Kustanowitz (jackk@atomica.com)
 158 Original version
 159
 160 29 September 2003: Brodie Thiesfield (code@jellycan.com)
 161 Rewritten as C plugin for gsoap. Bugs fixed and features added.
 162
 163 14 January 2004: Brodie Thiesfield (code@jellycan.com)
 164 Bug fix.
 165
 166 17 March 2009: Brodie Thiesfield (code@jellycan.com)
 167 Clean up and re-release.
 168 */
 169
 170 #ifndef INCLUDED_gsoapWinInet2_h
 171 #define INCLUDED_gsoapWinInet2_h
 172
 173 #include <stdsoap2.h>
 174 #include <wininet.h>
 175
 176 #ifdef __cplusplus
 177 extern "C" {
 178 #endif
 179
 180 typedef enum {
 181     rseFalse = 0,
 182     rseTrue,
 183     rseDisplayDlg
 184 } wininet_rseReturn;
 185
 186 typedef wininet_rseReturn(*wininet_rse_callback)(HINTERNET a_hHttpRequest, DWORD a_dwErrorCode);
 187
 188 extern void wininet_set_rse_callback(struct soap *a_pSoap, wininet_rse_callback a_pRseCallback);
 189
 190 extern int wininet_plugin(struct soap *a_pSoap, struct soap_plugin *a_pPluginData, void *a_pUnused);
 191
 192 #ifdef __cplusplus
 193 }
 194 #endif
 195
 196 #endif // INCLUDED_gsoapWinInet2_h