Copyright © 2001 WorldCom, Inc.
In order to demonstrate the use of the wctpXml library, wctpXml includes an example application, w32Example. This examples connects to a user-defined WCTP gateway and invokes either a wctp-VersionQuery or a wctp-SubmitClientMessage operation, displaying the actual HTTP/XML/WCTP sent and received. w32Example builds using the Microsoft Visual C++ 6.0 compiler and executes under Windows 95 or higher. It is a console application, meaning that it runs from a command line interface and has no windows of its own.
In addition to the wctpXml library components, w32Example includes and uses the following files in the example directory:
File |
Purpose |
w32Example.cpp |
This file contains the main( ) program. It accepts command line input and makes a WCTP operation invocation against a WCTP server, displaying the output (the response returned) in the console window. |
w32Example.dsp |
This is the Visual C++ 6.0 project file for the example application, w32Example. Use this project file to build an executable, w32Example. |
w32Example.dsw |
This is the Visual C++ 6.0 workspace file for the example application, w32Example. Use this workspace file to access the w32Example project. |
w32InetConnection.cpp |
This file contains the w32InetConnection class definition for establishing an Internet socket connection (TCP/IP). w32InetConnection is the base class for w32WctpConnection (see below). |
w32InetConnection.hpp |
This file contains the w32InetConnection class declaration for establishing an Internet socket connection (TCP/IP). w32InetConnection is the base class for w32WctpConnection (see below). |
w32WctpConnection.cpp |
This file contains the w32WctpConnection class definition for establishing a WCTP socket connection (TCP/IP). w32WctpConnection has w32InetConnection as a base class. It offers some useful operations regarding encoding, and assumes that the contents being sent/received is WCTP/XML. |
w32WctpConnection.hpp |
This file contains the w32WctpConnection class declaration for establishing a WCTP socket connection (TCP/IP). w32WctpConnection has w32InetConnection as a base class. It offers some useful operations regarding encoding, and assumes that the contents being sent/received is WCTP/XML. |
To build the example application, w32Example, do the following:
1. Build the wctpXml (and xmlparse) libraries. You can do this as follows:
a) Open the wctpxml.dsw file in the wctpXml\bin directory, and then select “Build/Rebuild All” from the menu.
b) The xmlparse.dll and xmltok.dll libraries are available pre-built in the wctpXml\expat\bin directory. You can rebuild them if you wish by opening the expat.dsw file in the wctpXml\expat directory, and then for each project (under the “Project\Set Active Project” menu), select “Build\Rebuild All” from the menu. You will need to either register the xmlparse.dll and xmltok.dll libraries, or copy them into the same directory where the w32Example.exe file is run.
2. Open the w32Example.dsw project file, and then select "Build/Rebuild All" from the menu. By default, a wctpXml\example\Debug directory will be created and the newly built w32example.exe file will be placed there. (Again, if you decide not to register Expat’s xmlparse.dll and xmltok.dll libraries, be sure to copy them from the wctpXml\expat\bin directory to the directory where you run the w32example.exe file from, otherwise you may get a missing dll error message).
To run the w32Example, open a command line or console window in Windows 95 or higher, change directory to the wctpXml\example\Debug directory, and issue the following command:
w32Example -h <host> -p <port> -a <path> [-r <recipient>]
The first argument, w32Example, is the name of the executable itself. Use the –h option to specify the host/server’s address (IP address or domain name). Use the –p option to specify the port at the host/server address for the socket connection. Use the –a option to specify the path at the host/server for the specific application/script to handle your request. These three options are required in order to make a valid WCTP connection. To determine what each of these values should be, contact the carrier or WCTP service provider to whom you wish to connect. Use the last option,–r, to specify a recipient (account ID or PIN) on the server’s system to whom you want to send a message. If this option is present, w32Example will generate a wctp-SubmitClientMessage request and display the resulting wctp-SubmitClientResponse. If it is not present, w32Example will generate a wctp-VersionQuery request and display the resulting wctp-VersionResponse.
For example, to generate a wctp-VersionQuery:
w32Example -h 123.456.12.23 -p 80 -a /wctp
or, to generate a wctp-SubmitClientMessage to recipient 1234567:
w32Example -h 123.456.321.2 -p 80 -a /wctp –r 1234567
where you replace the IP address, port number, and recipient pin number with valid values for testing.
To debug the w32Example application, use the dynamic debugger built into Visual C++.
w32Example is analogous to the wctpXml_client example provided for Linux. It begins in the main( ) operation:
1. read the command line arguments using argc and argv. The host address, port, and path options are required, although they may be in any order relative to each other
2. echo the command line values to stdout
3. if the command line included a –r option (a recipient ID), the next step is to call do_SubmitClientMessage( ) using the recipient ID as the recipient of the message
4. if no –r option was found on the command line, the next step is to call do_VersionQuery( )
Both do_SubmitClientMessage( ) and do_VersionQuery( ) generate a request in the same basic manner:
1. instantiate a wctpXml request class and the correct wctpXml response class
2. fill the request attributes using the SetYYY( ) operations. In the cases of optional sub-elements, you must call the HoldYYYY( ) operation(s) to tell the request what optional sub-element(s) it will be holding before you try to access them. For a specific example, see the code surrounding the “pPayload->HoldAlphanumeric( )” call in do_SubmitClientMessage( ).
3. pass the request and response to do_request( ), a generic routine that works for any WCTP request/response pair
do_request( ) proceeds to send the request and obtain the response:
1. ask the request object for its WCTP/XML string using the virtual AssembleRequestString( ) operation
2. wrap an HTTP 1.0 header around the WCTP/XML string
3. echo the actual HTTP 1.0-wrapped WCTP/XML string to stdout
4. open a connection to the WCTP server using the w32WctpConnection class operation open_conn( )
5. write the WCTP/XML request string to the WCTP server using the w32WctpConnection class operation write_xml( )
6. read the WCTP/XML response string from the WCTP server using the w32WctpConnection class operation read_xml( )
7. close the connection to the WCTP server using the w32WctpConnection class operation close_conn( )
8. echo the entire HTTP response received to stdout
9. locate the beginning of the WCTP/XML portion of the response, and strip off the HTTP header
10. pass the WCTP/XML response string (minus the HTTP header) to the response object using the Parse( ) operation
Both do_SubmitClientMessage( ) and do_VersionQuery( ) proceed in the same manner with the response:
1. check the operation type of the response returned (this should not be necessary, but is optionally available)
2. echo the attributes to stdout, “walking” down the nested elements to reach all of the values and attributes of the response. For each optional or mutually exclusive sub-element, use the GetXXXXType( ) operations on the parent element. For a specific example, see the code surrounding the “response.GetVersionQueryResponseType( )” call in do_VersionQuery( ). For each sub-element for which multiples may exist, use the NumXXXX( ) and GetXXXX( i ) operations on the parent element. For a specific example, see the code surrounding the “response.NumVersionDTDSupport( )” call in do_VersionQuery( ).