gSOAP2.8.17用户手册：快速入门与互操作性指南

5星 · 超过95%的资源需积分: 9 22 浏览量更新于2024-07-23 收藏 890KB PDF 举报

"gSOAP2.8.17 User Guide 是GENIVIA公司由Robert van Engelen编写的最新英文版用户手册，发布日期为2014年4月10日。该指南涵盖了gSOAP的不同版本之间的差异，以及快速入门教程，包括如何开发Web服务客户端应用程序、Web服务和XML数据绑定。此外，还涉及了互操作性、快速用户指南等内容，详细指导用户如何构建SOAP/XML客户端，生成C++客户端代理类，处理XML命名空间，以及指定输出参数等技术细节。" gSOAP2.8.17是用于构建Web服务和网络应用程序的一个开源工具包，它提供了C和C++的接口，使得开发者可以方便地实现SOAP（简单对象访问协议）和XML（可扩展标记语言）的处理。本用户手册旨在帮助开发者快速理解和使用gSOAP。在介绍部分，手册引导用户从基础开始，逐步深入到高级功能。1.1节"Getting Started"介绍了如何开始使用gSOAP，包括安装和配置环境。1.2和1.3节分别针对Web服务客户端应用和Web服务的开发提供快速启动指南，帮助开发者迅速搭建基本框架。1.4节"QuickStart: XML Data Bindings"则涉及了如何利用XML数据绑定来简化数据处理。章节2"Notational Conventions"定义了手册中使用的符号和约定，确保读者能正确理解文档中的技术描述。随后的章节对比了gSOAP不同版本之间的变化，如3.x至2.x、2.2至2.1及更早版本的区别，这些差异可能影响到升级和兼容性问题。 7.x章节是快速用户指南，详细阐述了实际开发过程中的关键步骤。7.1.1"如何构建SOAP/XML客户端"提供了一个实例，展示了从零开始创建客户端的基本流程。7.1.2至7.1.14则深入讲解了XML命名空间、生成C++客户端代理类、处理不同类型的数据输出等复杂话题，每个子节都通过示例代码来辅助解释，使开发者能够更好地掌握实际操作。例如，7.1.4节"如何生成C++客户端代理类"介绍了利用gSOAP的代码生成工具自动创建与Web服务交互的C++类的方法，而7.1.9节"如何指定多个输出参数"则指导开发者如何处理返回多个结果的情况。7.1.11节则关注于结构体或类复合数据类型的输出参数，7.1.14节讨论了匿名参数的处理，这些都是在实际开发中经常遇到的问题。 gSOAP2.8.17 User Guide是一份详尽的参考资料，对于使用gSOAP进行Web服务开发的程序员来说，是不可或缺的工具，它覆盖了从入门到高级应用的各个方面，有助于提高开发效率和代码质量。

soap end(ctx); // clean up allocated temporaries

soap free(ctx); // delete context

The ctx gSOAP engine context (type struct soap) controls settings and holds state, such as XML

formatting, (e.g. SOAP XML INDENT), serialization options, current state, and I/O settings. Simply

set the output stream (std::ostream) ctx->os of the context to redirect the content, e.g. to a ﬁle

or string. Also, when serializing a graph rather than an XML tree (SOAP XML TREE option forces

trees) the XML output conforms to SOAP encoding for object graphs based on id-ref, see Section 7.5

for details.

To read the XML representation from standard input into a book object, use:

soap *ctx = soap new1(SOAP XML STRICT); // new context with option

book bk;

if (soap read book(ctx, &bk) != SOAP OK) ... error ...

else

cout ¡¡ bk.isbn ¡¡ ”, ” ¡¡ bk.title ¡¡ ”, ” ¡¡ bk.publisher ¡¡ endl;

... further use of bk ...

soap destroy(ctx); // delete deserialized objects

soap end(ctx); // delete temporaries

soap free(ctx); // delete context

Automatic built-in XML validation (enabled with SOAP XML STRICT) ensures that data members

are present so we can safely print them in this example, thus ensuring consistency of data with the

XML schema. Set the ctx->is input stream to read from a ﬁle/string stream instead of stdin.

The soap destroy and soap end calls deallocate the deserialized content, so use with care. In general,

memory management is automatic in gSOAP to avoid leaks.

The above uses a very simple example schema. The gSOAP toolkit handles all XML schema con-

structs deﬁned by the XML schema standard. The toolkit is also able to (de)serialize pointer-based

C/C++ data structures (including cyclic graphs), structs/classes, unions, enums, STL containers,

and even special data types such as struct tm. Therefore, the toolkit works in two directions: from

WSDL/schema to C/C++ and from C/C++ to WSDL/schema.

The gSOAP toolkit also handles multiple schemas deﬁned in multiple namespaces. Normally the

namespace preﬁxes of XML namespaces are added to the C/C++ type deﬁnitions to ensure type

uniqueness. For example, if we would combine two schemas in the same application where both

schemas deﬁne a book object, we need to resolve this conﬂict. In gSOAP this is done using names-

pace preﬁxes, rather than C++ namespaces (research has pointed out that XML namespaces are

not equivalent to C++ namespaces). Thus, the book class might actually be bound to an XML

namespace and the class would be named ns book, where ns is bound to the corresponding names-

pace.

The following options are available to control serialization:

soap-¿encodingStyle = NULL; // to remove SOAP 1.1/1.2 encodingStyle

soap mode(soap, SOAP XML TREE); // XML without id-ref (no cycles!)

soap mode(soap, SOAP XML GRAPH); // XML with id-ref (including cycles)

soap set namespaces(soap, struct Namespace *nsmap); //to set xmlns bindings

Other ﬂags can be used to format XML, see Section 9.12.

More information on XML databinding support for C and C++, see Section 7.5.

1.5 Feature Overview

The highlights of gSOAP are:

• Unique interoperability features: the tools generate type-safe SOAP marshalling routines to

(de)serialize native and user-deﬁned C and C++ data structures.

• Support WSDL 1.1, WSDL 2.0, SOAP 1.1, SOAP 1.2, SOAP RPC encoding style, and

document/literal style. gSOAP is one of the few SOAP toolkits that support the full range of

SOAP 1.1 RPC encoding features including sparse multi-dimensional arrays and polymorphic

types. For example, a service operation with a base class parameter may accept derived class

instances from a client. Derived class instances keep their identity through dynamic binding.

The toolkit also supports all XSD schema type constructs and has been tested against the

W3C XML Schema Patterns for Databinding Interoperability working group and of gSOAP

release 2.8.x passes all tests.

• Supports WS-Security, WS-Addressing, WS-ReliableMessaging, C14N exclusive canonicaliza-

tion. The protocols are implemented using code generation with wsdl2h and soapcpp2. The

gSOAP tools can be used to generate messaging protocols for other WS-* protocols.

• gSOAP supports XML-RPC and RSS protocols. Examples are provided.

• JSON support is included in the XML-RPC library to switch between XML-RPC and JSON

protocols. For more details, see the samples/xml-rpc-json folder in the package.

• The wsdl2h tool supports WS-Policy. Policy assertions are included in the generated service

description header ﬁle with recommendations and usage hints.

• gSOAP supports MIME (SwA), DIME, and MTOM attachments and has streaming capabil-

ities to direct the data stream to/from resources. gSOAP is the only toolkit that supports

streaming MIME, DIME, and MTOM attachment transfers, which allows you to exchange

binary data of practically unlimited size in the fastest possible way (streaming) while ensuring

the usefulness of XML interoperability.

• gSOAP supports SOAP-over-UDP.

• gSOAP supports IPv4 and IPv6.

• gSOAP supports Zlib deﬂate and gzip compression (for HTTP, TCP/IP, and XML ﬁle stor-

age).

• gSOAP supports SSL (HTTPS) using OpenSSL.

• gSOAP supports HTTP/1.0, HTTP/1.1 keep-alive, chunking, basic authentication, and digest

authentication using a plugin.

• gSOAP supports SOAP one-way messaging.

• The schema-speciﬁc XML pull parser is fast and eﬃcient and does not require intermediate

data storage for demarshalling to save space and time.

• The soapcpp2 compiler includes a WSDL and schema generator for convenient Web Service

publishing.

• The soapcpp2 compiler generates sample input and output messages for veriﬁcation and testing

(before writing any code). An option (-T) can be used to automatically implement echo

message services for testing.

• The WSDL importer wsld2h (converts to gSOAP header ﬁles) for automated client and server

development.

• Generates source code for stand-alone Web Services and client applications.

• Ideal for small devices such as Palm OS, Symbian, Pocket PC, because the memory footprint

is small.

• Ideal for building web services that are compute-intensive and are therefore best written in

C and C++.

• Platform independent: Windows, Unix, Linux, Mac OS X, Pocket PC, Palm OS, Symbian,

VXWorks, etc.

• Supports serializing of application’s native C and C++ data structures, which allows you to

save and load XML serialized data structures to and from ﬁles.

• Selective input and output buﬀering is used to increase eﬃciency, but full message buﬀering

to determine HTTP message length is not used. Instead, a three-phase serialization method is

used to determine message length. As a result, large data sets such as base64-encoded images

can be transmitted with or without DIME attachments by small-memory devices such as

PDAs.

• Supports C++ single class inheritance, dynamic binding, overloading, arbitrary pointer struc-

tures such as lists, trees, graphs, cyclic graphs, ﬁxed-size arrays, (multi-dimensional) dy-

namic arrays, enumerations, built-in XSD Schema types including base64Binary encoding,

and hexBinary encoding.

• No need to rewrite existing C/C++ applications for Web service deployment. However, parts

of an application that use unions, pointers to sequences of elements in memory, and void* need

to be modiﬁed, but only if the data structures that adopt them are required to be serialized

or deserialized as part of a service operation invocation.

• Three-phase marshalling: 1) analysis of pointers, single-reference, multi-reference, and cyclic

data structures, 2) HTTP message-length determination, and 3) serialization as per SOAP

1.1 encoding style or user-deﬁned encoding styles.

• Two-phase demarshalling: 1) SOAP parsing and decoding, which involves the reconstruction

of multi-reference and cyclic data structures from the payload, and 2) resolution of ”forward”

pointers (i.e. resolution of the forward href attributes in SOAP).

• Full and customizable SOAP Fault processing (client receive and service send).

• Customizable SOAP Header processing (send and receive), which for example enables easy

transaction processing for the service to keep state information.

2 Notational Conventions

The typographical conventions used by this document are:

Sans serif or italics font denotes C and C++ source code, ﬁle names, and shell/batch commands.

Bold font denotes C and C++ keywords.

Courier font denotes HTTP header content, HTML, XML, XML Schema content and WSDL

content.

[Optional] denotes an optional construct.

The keywords ”MUST”, ”MUST NOT”, ”REQUIRED”, ”SHALL”, ”SHALL NOT”, ”SHOULD”,

”SHOULD NOT”, ”RECOMMENDED”, ”MAY”, and ”OPTIONAL” in this document are to be

interpreted as described in RFC-2119.

3 Diﬀerences Between gSOAP Versions 2.4 (and Earlier) and 2.5

To comply with WS-I Basic Proﬁle 1.0a, gSOAP 2.5 and higher adopts SOAP document/literal

by default. There is no need for concern, because the WSDL parser wsdl2h automatically takes

care of the diﬀerences when you provide a WSDL document, because SOAP RPC encoding, literal,

and document style are supported. A new soapcpp2 compiler option was added -e for backward

compatibility with gSOAP 2.4 and earlier to adopt SOAP RPC encoding by default in case you

want to develop a service that uses SOAP encoding. You can also use the gSOAP soapcpp2 compiler

directives to specify SOAP encoding for individual operarations, when desired.

4 Diﬀerences Between gSOAP Versions 2.1 (and Earlier) and 2.2

You should read this section only if you are upgrading from gSOAP 2.1 to 2.2 and later.

Run-time options and ﬂags have been changed to enable separate recv/send settings for transport,

content encodings, and mappings. The ﬂags are divided into four classes: transport (IO), content

encoding (ENC), XML marshalling (XML), and C/C++ data mapping (C). The old-style ﬂags

soap disable X and soap enable X, where X is a particular feature, are deprecated. See Section 9.12

for more details.

5 Diﬀerences Between gSOAP Versions 1.X and 2.X

You should read this section only if you are upgrading from gSOAP 1.X to 2.X.

gSOAP versions 2.0 and later have been rewritten based on versions 1.X. gSOAP 2.0 and later is

thread-safe, while 1.X is not. All ﬁles in the gSOAP 2.X distribution are renamed to avoid confusion

with gSOAP version 1.X ﬁles:

gSOAP 1.X gSOAP 2.X

soapcpp soapcpp2

soapcpp.exe soapcpp2.exe

stdsoap.h stdsoap2.h

stdsoap.c stdsoap2.c

stdsoap.cpp stdsoap2.cpp

Changing the version 1.X application codes to accommodate gSOAP 2.X does not require a signif-

icant amount of recoding. The change to gSOAP 2.X aﬀects all functions deﬁned in stdsoap2.c[pp]

(the gSOAP runtime context API) and the functions in the sources generated by the gSOAP

soapcpp2 compiler (the gSOAP RPC+marshalling API). Therefore, clients and services developed

with gSOAP 1.X need to be modiﬁed to accommodate a change in the calling convention used in

2.X: In 2.X, all gSOAP functions (including the service operation proxy routines) take an addi-

tional parameter which is an instance of the gSOAP runtime context that includes ﬁle descriptors,

tables, buﬀers, and ﬂags. This additional parameter is always the ﬁrst parameter of any gSOAP

function.

The gSOAP runtime context is stored in a struct soap type. A struct was chosen to support applica-

tion development in C without the need for a separate gSOAP implementation. An object-oriented

approach with a class for the gSOAP runtime context would have prohibited the implementation

of pure C applications. Before a client can invoke service operations or before a service can accept

requests, a runtime context needs to be allocated and initialized. Three new functions are added

to gSOAP 2.X:

Function

Description

soap init(struct soap *soap) Initializes a context (required only once)

struct soap *soap new() Allocates, initializes, and returns a pointer to a runtime

context

struct soap *soap copy(struct soap *soap) Allocates a new runtime context and copies contents of the

context such that the new environment does not share any

data with the original context

A context can be reused as many times as necessary and does not need to be reinitialized in doing

so. A dynamically allocated context is deallocated with soap free.

A new context is only required for each new thread to guarantee exclusive access to a new runtime

context by each thread. For example, the following code stack-allocates the runtime context which

is used for multiple service operation calls:

int main()

{

剩余286页未读，继续阅读

bjwzhscs

粉丝: 1
资源: 3

gSOAP2.8.17用户手册：快速入门与互操作性指南

gsoap user guide

利用gsoap2.8.17生成onvif.h头文件

soapdoc2（gSOAP 2.7.8 User Guide）

gsoap_2.8.17

gSoap_2.8.17_实例文件_VS2010

gSOAP 2.8.11 User Guide: 必读的英文Web服务开发资源

gSoap-2.8.14_User_Guide.pdf

gSOAP User Guild

gsoap

gsoap.rar_gSoap-2.8_gsoap_gsoap vc6_gsoap使用详解

最新资源