gSOAP 2.8用户指南：快速入门与特性概览

需积分: 1 129 浏览量更新于2024-07-24 收藏 887KB PDF 举报

"gsoap 2.8文档是关于gSOAP 2.8版本的一个用户指南，由Robert van Engelen编写，GENIVIA公司发行，日期为2013年8月25日。该文档主要介绍了如何使用gSOAP进行Web服务客户端和服务器应用的开发，以及XML数据绑定，并提供了不同gSOAP版本之间的差异对比。此外，还包含快速用户指南，指导用户如何构建SOAP/XML客户端，如何生成C++客户端代理类，处理XML命名空间，指定输出参数等。" gSOAP是一个开源工具包，用于在C和C++中实现基于SOAP（Simple Object Access Protocol）的Web服务和网络通信。这个文档是针对gSOAP 2.8.16版本的，它包含了以下关键知识点： 1. **入门**：文档首先介绍了如何开始使用gSOAP，包括快速启动Web服务客户端和服务器应用的开发，以及XML数据绑定的基本步骤。 2. **功能概述**：这部分详细列出了gSOAP 2.8版本的主要特性，可能包括了HTTP/HTTPS传输支持、SOAP协议处理、XML解析和生成、类型编码、错误处理等。 3. **不同版本间的差异**：文档比较了gSOAP 2.4及更早版本与2.5、2.1及更早版本与2.2、1.x与2.x版本之间的差异，帮助用户了解升级或迁移时需要注意的问题。 4. **互操作性**：gSOAP强调与各种其他SOAP实现的兼容性，这部分可能讨论了如何确保gSOAP应用与其他平台或语言的Web服务顺利交互。 5. **快速用户指南**：这部分是实际操作的指南，详细讲述了如何构建SOAP/XML客户端，包括生成C++客户端代理类、处理XML命名空间、指定输出参数等。例如，如何改变响应元素名称，如何处理包含结构或类复合数据类型的输出参数，以及如何指定匿名参数名等。 6. **示例**：每个指导部分都包含具体的代码示例，帮助开发者直观地理解如何在实践中应用这些概念和技术。 gSOAP 2.8文档对于开发基于C或C++的SOAP Web服务的开发者来说是一份宝贵的资源，它不仅提供了理论知识，还提供了丰富的实践指导，帮助开发者高效地利用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()

{

剩余285页未读，继续阅读

shizhouhu

粉丝: 4
资源: 10

gSOAP 2.8用户指南：快速入门与特性概览

gsoap_2.8.36.zip

gSOAP的中文文档

gsoap 2.8 (SOAP/XML 关于C/C++ 语言的自动化实现工具内附 CSharp webservice例子,及GSOAP client和server例子)

使用gSOAP在C中调用Web服务

gSOAP：C++开发Web服务详解与应用

gSOAP中文教程：从安装到实战应用详解

江西师范大学科学技术学院在四川2020-2024各专业最低录取分数及位次表.pdf

麒麟win10双系统重新安装win10后麒麟启动菜单看不到解决方法

多邻国Duolingo v6.0.3 高级版.apk

QT网络编程: 实现TCP通讯设置（客户端）

最新资源