← Back to branch summary

~ifolder-dev/simias/trunk-packaging

« back to all changes in this revision

Viewing changes to tools/gsoap/gsoap-linux-2.7/mod_gsoap/gsoap_win/wininet/.svn/text-base/README.txt.svn-base

  • Committer: Jorge O. Castro
  • Date: 2007-12-03 06:56:46 UTC
  • Revision ID: jorge@ubuntu.com-20071203065646-mupcnjcwgm5mnhyt
* Remove a bunch of .svn directories we no longer need.

Show diffs side-by-side

added added

removed removed

Lines of Context:
tools/gsoap/gsoap-linux-2.7/mod_gsoap/gsoap_win/wininet/.svn/text-base/README.txt.svn-base
1
 
 
2
 
WinInet plugin - supports Windows WinInet transport
3
 
 
4
 
Purpose: Allow gsoap clients (not servers) to direct all communications 
5
 
         through the WinInet API. This automatically provides all of the 
6
 
         proxy and authentication features supported by the control panel 
7
 
         'Internet Options' dialog to the client. As these options are 
8
 
         shared by IE, this means that "if IE works, gsoap works."
9
 
 
10
 
Features:
11
 
         + gsoap plugin - extremely easy to use
12
 
         + complete support for:
13
 
             - HTTP/1.0 and HTTP/1.1
14
 
             - HTTPS (no extra libraries are required)
15
 
             - HTTP authentication
16
 
             - Proxy servers (simple, automatic discovery, etc)
17
 
             - Proxy authentication (basic, NTLM, etc)
18
 
         + authentication prompts and HTTPS warnings (e.g. invalid HTTPS CA) 
19
 
             can be resolved by the user via standard system dialog boxes.
20
 
         + message size is limited only by available memory
21
 
         + connect, receive and send timeouts are used 
22
 
         + supports all SOAP_IO types (see limitations)
23
 
         + written completely in C, can be used in C, C++, and MFC projects
24
 
             without modification (anywhere that gsoap is used)
25
 
         + can be used in both MBCS and UNICODE projects
26
 
         + compiles cleanly at warning level 4 (if gsoap uses SOAP_SOCKET
27
 
             for the definition of sockets instead of int, it will also
28
 
             compile without win64 warnings).
29
 
         + all debug trace goes to the gsoap TEST.log file 
30
 
         + supports multiple threads (all plugin data is stored in the 
31
 
             soap structure - no static variables)
32
 
 
33
 
Limitations:
34
 
         - DIME attachments are not supported
35
 
         - may internally buffer the entire outgoing message before sending
36
 
             (if the serialized message is larger then SOAP_BUFLEN, or if 
37
 
             SOAP_IO_CHUNK mode is being used then the entire message will 
38
 
             be buffered)
39
 
 
40
 
Usage:   Add the gsoapWinInet2.h and gsoapWinInet2.cpp files to your project 
41
 
         (if you have a C project, rename gsoapWinInet2.cpp to .c and use
42
 
         it as is). Ensure that you turn off precompiled headers for the 
43
 
         .cpp file.
44
 
 
45
 
         In your source, just after calling soap_init(), register this 
46
 
         plugin with soap_register_plugin( soap, wininet_plugin ). 
47
 
 
48
 
         e.g.
49
 
             struct soap soap;
50
 
             soap_init( &soap );
51
 
             soap_register_plugin( &soap, wininet_plugin );
52
 
             soap.connect_timeout = 5; // this will be used by wininet too
53
 
             ...
54
 
             soap_done(&soap);
55
 
 
56
 
Notes:   For extra control, you may also register this plugin using the 
57
 
         soap_register_plugin_arg() function, and supply as the argument 
58
 
         flags which you wished to be passed to HttpOpenRequest. 
59
 
 
60
 
         e.g.
61
 
             struct soap soap;
62
 
             soap_init( &soap );
63
 
             soap_register_plugin_arg( &soap, wininet_plugin,
64
 
                 (void*) INTERNET_FLAG_IGNORE_CERT_CN_INVALID );
65
 
 
66
 
         See the MSDN documentation on HttpOpenRequest for details of 
67
 
         available flags. The <wininet.h> header file is required for the 
68
 
         definitions of the flags. Some flags which may be useful are:
69
 
 
70
 
             INTERNET_FLAG_KEEP_CONNECTION
71
 
             Uses keep-alive semantics, if available, for the connection. 
72
 
             This flag is required for Microsoft Network (MSN), NT LAN 
73
 
             Manager (NTLM), and other types of authentication. 
74
 
             ++ Note that this flag is used automatically when soap.omode 
75
 
             has the SOAP_IO_KEEPALIVE flag set. ++
76
 
 
77
 
             INTERNET_FLAG_IGNORE_CERT_CN_INVALID
78
 
             Disables Microsoft Win32 Internet function checking of SSL/PCT-
79
 
             based certificates that are returned from the server against 
80
 
             the host name given in the request. 
81
 
 
82
 
             INTERNET_FLAG_IGNORE_CERT_DATE_INVALID
83
 
             Disables Win32 Internet function checking of SSL/PCT-based 
84
 
             certificates for proper validity dates.
85
 
 
86
 
         This plugin uses the following callback functions and is not 
87
 
         compatible with any other plugin that uses these functions.
88
 
 
89
 
             soap->fopen
90
 
             soap->fposthdr
91
 
             soap->fsend
92
 
             soap->frecv
93
 
             soap->fclose
94
 
 
95
 
         If there are errors in sending the HTTP request which would 
96
 
         cause a dialog box to be displayed in IE (for instance, invalid
97
 
         certificates on an HTTPS connection), then a dialog will also
98
 
         be displayed by this library. At the moment is is not possible
99
 
         to disable the UI. If you wish to remove the UI then you will 
100
 
         need to hack the source to remove the dialog box and resolve the
101
 
         errors programmatically, or supply the appropriate flags in
102
 
         soap_register_plugin_arg() to disable the unwanted warnings.
103
 
 
104
 
         Because messages are buffered internally to gsoapWinInet2 plugin
105
 
         it is recommended that the SOAP_IO_STORE flag is not used otherwise
106
 
         the message may be buffered twice on every send. Use the default
107
 
         flag SOAP_IO_BUFFER, or SOAP_IO_FLUSH.
108
 
 
109
 
License and redistribution: 
110
 
         This code is released under the gSOAP public license.
111
 
 
112
 
         The contents of this file are subject to the gSOAP Public License
113
 
         Version 1.3 (the "License"); you may not use this file except in
114
 
         compliance with the License. You may obtain a copy of the License at
115
 
         http://www.cs.fsu.edu/~engelen/soaplicense.html Software distributed
116
 
         under the License is distributed on an "AS IS" basis, WITHOUT
117
 
         WARRANTY OF ANY KIND, either express or implied. See the License for
118
 
         the specific language governing rights and limitations under the
119
 
         License.
120
 
 
121
 
Developers:
122
 
         26 May 2003: Jack Kustanowitz (jackk@atomica.com)
123
 
         Original version
124
 
 
125
 
         29 September 2003: Brodie Thiesfield (bt@jellycan.com)
126
 
         Rewritten as C plugin for gsoap. Bugs fixed and features added.
127
 
 
128
 
         14 January 2004: Brodie Thiesfield (bt@jellycan.com)
129
 
         Bug fix.