Gsoap Chinese Document (8.1.1)

8. Quick Guide
This guide aims to help you quickly start your gsoap development journey. After reading this section, you need to have a general understanding of the soap 1.1 protocol and C/C ++ syntax. Although the gsoap compiler can be used to write Web Services and client programs directly in C/C ++ without understanding the details of the SOAP protocol, however, since we have used a large number of instances in this section to illustrate the connection and communication between gsoap and other soap implementations, it is also necessary to understand some soap and WSDL protocols.
 
8.1 how to use the gsoap compiling environment to compile the soap client program
Generally, the implementation of a soap client application requires a stub routine (stub routine) for each remote method that the client needs to call ). The stub routine is mainly used to encode the parameter information. It sends the call request containing the parameter information to the developed soap service, waits for the returned result, and encodes the parameter information in the result. The client program calls a stub routine to access a remote method, just like calling a local method. Using C/C ++ to manually write a stub routine is very painful, especially when the remote method parameters contain specific data structures (such: record, array, graph, etc. Fortunately, the 'wsdl2h 'WSDL parser and the 'soapcpp2' stub and architecture compiler in the gsoap package can automate the development of the web service client and server.
The 'soapcpp2 'stub and architecture compiler are pre-compilers that can generate the C ++ source code required to build the C ++ soap client. The input parameter of the pre-compiler is a standard C/C ++ header file. This header file can be automatically generated by the WSDL parser according to the relevant WSDL document.
See the following command:
$ Wsdl2h-O quote. h http://services.xmethods.net/soap/urn:xmethods-delayed-quotes.wsdl
The preceding command generates a C ++ syntax structure header file based on the WSDL document provided by the URL.
To generate a pure C header file, run the following command:
$ Wsdl2h-c-o quote. h http://services.xmethods.net/soap/urn:xmethods-delayed-quotes.wsdl
For more information about the WSDL parser and its options, see section 8.2.10.
After executing the preceding command, the quote. h file is generated. It contains the definition of the stub routine of the Development client or server program. The soap service remote method is defined in this header file as a function declaration. The C/C ++ source code's Stub routine will be automatically implemented through the pre-compiler. At the same time, the program framework of each remote method is also automatically generated, which can be used to create a SOAP server program application.
The input and output parameters of the soap service can be simple data types or complex data structures, which can be automatically generated or manually defined by the WSDL parser. The pre-compiler will automatically generate code for serialization/deserialization of the data so that the stub routine can encode or decode the data in XML format.

8.1.1 example
The xmethods delayed stock quote Service provides a getquote method (defined by quote. h generated by the 'wsdl2' WSDL parser ). This method returns the corresponding stock price based on the provided stock name. The following is the WSDL document information for this method:

Endpoint URL: http://services.xmethods.net: 80/soap
Soap action: "" (2 quotes)
Remote Method namespace: urn: xmethods-delayed-quotes
Remote Method Name: getquote
Input parameter: Symbol of Type XSD: String
Output parameter: Result of Type XSD: Float
 
The following is the getquote. h header file generated by the WSDL Parser (the actual file content is related to the 'wsdl2' version and generation options ):
// Gsoap NS1 service name: net_dotxmethods_dotservices_dotstockquote_dotstockquotebinding
// Gsoap NS1 service type: net_dotxmethods_dotservices_dotstockquote_dotstockquoteporttype
// Gsoap NS1 service port: http: // 66.28.98.121: 9090/soap
// Gsoap NS1 service namespace: urn: xmethods-delayed-quotes
// Gsoap NS1 service documentation: Definitions generated by the gsoap WSDL parser 1.0
// Service net. xmethods. Services. stockquote. stockquoteservice: net. xmethods. Services. stockquote. stockquote Web Service

// Gsoap NS1 service method-style: getquote RPC
// Gsoap NS1 service method-encoding: getquote http://schemas.xmlsoap.org/soap/encoding/
// Gsoap NS1 service method-Action: getquote urn: xmethods-delayed-quotes # getquote
Int NS1 _ getquote (char * symbol, float & result );

This header file uses C/C ++ code to specify the details of the web service for the gsoap pre-compiler. The remote method is defined as the NS1 _ getquote function, and all the details required by the client to call the Web service are specified.
The getquote remote method requires a string named symbol as the input parameter, and a floating point number named result as the output parameter. In the remote method call function generated by the Pre-compiler, the last parameter must be an output parameter, which is passed in reference mode or defined as a pointer type. All other parameters are input parameters, which must be passed as values. The function returns an integer value indicating that the Web Service is successfully called or an error occurs. For more information about the error code, see section 10.2.
The details of the namespace prefix NS1 _ In the function name will be discussed in Section 8.1.2. In short, the namespace prefix and function name are separated by two underscores. For example, in NS1 _ getquote, NS1 is the namespace prefix, and getquote is the function name. (A single underline in the function name will be interpreted as a break number in XML, because the break number in XML is more commonly used than the underline. For details, see section 10.3)
Run the following command to execute the pre-compiler:
 
Soapcpp2 getquote. h

The pre-compiler generates the code framework of the stub routine based on the information defined in getquote. h. This stub routine can be called everywhere in the client program. The stub routine is declared as follows:

Int soap_call_ns1 _ getquote (struct soap * soap, char * URL, char * Action, char * symbol, float & result );

The stub routine is stored in the soapclient. cpp file. The soapc. cpp file contains functions for serializing and deserializing data. You can use the-C compilation option to generate pure C code.
Note: soap_call_ns1 _ getquote adds three parameters based on the NS1 _ getquote parameter: Soap must be a valid pointer to a gsoap runtime environment; URL is the URL of the web service; action indicates the soap action required by the web service. The URL of the xmethods delayed stock quote service is http: // 66.28.98.121: 9090/soap, and action is "" (2 quotes ). You can dynamically change the URL and action. If the preceding two variables are defined as null, the information defined in the header file is used.
The following example calls a remote method to obtain IBM stock information:

# Include "soaph. H" // contains the generated stub routine Definition
# Include "net_dot_xmethods_dot_services_dot_stockquote_dot_stockquotebinding.nsmap" // contains the namespace table
Int main ()
{
Struct soap; // gsoap Runtime Environment
Float quote;
Soap_init (& soap); // initialize the runtime environment (only once)
If (soap_call_ns1 _ getquote (& soap, null, null, "IBM", & quote) = soap_ OK)
STD: cout <"Current IBM stock quote =" <quote <STD: Endl;
Else // an error occurred
Soap_print_fault (& soap, stderr); // the error message is displayed in stderr.
Soap_destroy (& soap); // deletes a class instance (for C ++ only)
Soap_end (& soap); // clear the runtime environment variable
Soap_done (& soap); // uninstall the runtime environment variable
Return 0;
}

After the call is successful, the stub routine returns soap_ OK AND THE QUOTE variable stores the stock information. If the call fails, an error is generated and the soap_print_fault function displays the error information.
The gsoap compiler also generates a proxy class for the c ++ client program.

# Include "soapnet_dot_xmethods_dot_services_dot_stockquote_dot_stockquotebindingproxy.h" // obtain the proxy
# Include "net_dot_xmethods_dot_services_dot_stockquote_dot_stockquotebinding.nsmap" // contains the namespace table
Int main ()
{
Net Q; // "Net" is the short name of the Service proxy class.
Float R;
If (Q. NS1 _ getquote ("IBM", R) = soap_ OK)
STD: cout <r <STD: Endl;
Else
Soap_print_fault (Q. Soap, stderr );
Return 0;
}

The constructor of the proxy class defines and initializes a gsoap environment variable instance. All HTTP and SOAP/XML processing is hidden in the background. You can change the Web service name in the header file generated by the WSDL parser. The Web Service name is extracted from the WSDL content and is not always in the short name format. You can change this entry at will.

// Gsoap NS1 service name: net_dot_xmethods_dot_services_dot_stockquote_dot_stockquotebinding

To use a more appropriate name. This name determines the name of the proxy file and the XML namespace table file.
The following function can be used to create a gsoap Runtime Environment (struct soap ):
Soap_init (struct soap * soap) initializes the runtime environment variable (only once required)
Soap_init1 (struct soap * soap, soap_mode iomode) initialize the runtime environment variable and set the in/out mode
Soap_init2 (struct soap * soap, soap_mode imode, soap_mode omode)
Struct soap * soap_new () defines, initializes the runtime environment, and returns a pointer to the execution Runtime Environment
Struct soap * soap_new1 (soap_mode iomode) defines and initializes the runtime environment, returns a pointer to the runtime environment, and sets the in/out mode.
Struct soap * soap_new2 (soap_mode imode, soap_mode omode) defines and initializes the runtime environment, returns a pointer to the runtime environment, and sets in/out modes respectively.
Struct soap * soap_copy (struct soap * soap) defines a new environment variable and assigns the existing environment information to the new variable
Soap_done (struct soap * soap) resets and closes connections to clear Environment Variables
 
Environment variables can be used in programs for any number of times. Each new thread needs a new environment variable instance.
When the client program in this example is executed, the SOAP request is called through the soap_call_ns1 _ getquote function, which generates the following soap rpc Request Information:
Post or soap HTTP/1.1
HOST: services.xmethods.net
Content-Type: text/XML
Content-Length: 529
Soapaction :""

<? XML version = "1.0" encoding = "UTF-8"?>
<SOAP-ENV: envelope xmlns: SOAP-ENV = "http://schemas.xmlsoap.org/soap/envelope"
Xmlns: SOAP-ENC = "http://schemas.xmlsoap.org/soap/encoding"
Xmlns: xsi = "http://www.w3.org/2001/XMLSchema-instance"
Xmlns: XSD = "http://www.w3.org/2001/XMLSchema"
Xmlns: NS1 = "urn: xmethods-delayed-quotes"
SOAP-ENV: encodingstyle = "http://schemas.xmlsoap.org/soap/encoding/">
SOAP-ENV: Body>
<NS1: getquote>
<Symbol> IBM </symbol>
</NS1: getquote>
SOAP-ENV: Body>
SOAP-ENV: envelope>

The xmethods delayed stock quote service returns the following information:
HTTP/1.1 200 OK
Date: sat, 25 Aug 2001 19:28:59 GMT
Content-Type: text/XML
Servers: Electric/1.0
Connection: keep-alive
Content-Length: 491

<? XML version = "1.0" encoding = "UTF-8"?>
<Soap: envelope xmlns: Soap = "http://schemas.xmlsoap.org/soap/envelope"
Xmlns: xsi = "http://www.w3.org/2001/XMLSchema-instance"
Xmlns: XSD = "http://www.w3.org/2001/XMLSchema"
Xmlns: soapenc = "http://schemas.xmlsoap.org/soap/encoding"
Soap: encodingstyle = "http://schemas.xmlsoap.org/soap/encoding?
<Soap: Body>
<N: getquoteresponse xmlns: N = "urn: xmethods-delayed-quotes?
<Result xsi: TYPE = "XSD: float? 41.81 </result>
</N: getquoteresponse>
</Soap: Body>
</Soap: envelope>

The information returned by the service is parsed by the stub routine and stored in the quote parameter of the soap_call_ns1 _ getquote function.
The client program can call the remote method multiple times at any time. See the following example:

...
Struct soap;
Float quotes [3]; char * myportfolio [] = {"IBM", "msdn "};
Soap_init (& soap); // need to initialize only once
For (INT I = 0; I <3; I ++)
If (soap_call_ns1 _ getquote (& soap, "http://services.xmethods.net: 80/soap", "", myportfolio [I], & quotes [I])! = Soap_ OK)
Break;
If (soap. Error) // an error occurred
Soap_print_fault (& soap, stderr );
Soap_end (& soap); // clean up all deserialized data
...

This client program obtains information for each stock code in the array by calling the NS1 _ getquote stub routine.
The above example demonstrates how easy it is to create a soap client using gsoap.