wctpXml Example Under Linux

Copyright © 2001 WorldCom, Inc.

In order to demonstrate the use of the wctpXml library, wctpXml includes an example application, wctpXml_client.  It 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. wctpXml_client builds and executes using the GNU C++ compiler version 2.96 under Redhat Linux 7 with a 2.2.16 kernel.

In addition to the wctpXml library components, the wctpXml_client example includes and uses the following files:

File

Purpose

debug.cfg

This file holds the “keys” that determine whether certain dynamic debugging information will be output to the debug.out file or not. See the DynaDebug.txt file for a full description.

DebugLabels.cpp

This file declares the labels used by DynaDebug for dynamic debugging. See the DynaDebug.txt file for a full description.

DebugLabels.hpp

This file declares an array of strings used by DynaDebug for dynamic debugging. See the DynaDebug.txt file for a full description.

DynaDebug.cpp

This file holds the DynaDebug class definition for dynamic debugging. See the DynaDebug.txt file for a full description.

DynaDebug.hpp

This file holds the DynaDebug class declaration for dynamic debugging. See the DynaDebug.txt file for a full description.

DynaDebug.txt

This file contains a full description of the DynaDebug class, along with information about the environment variables it uses, the debug.cfg input file, and the debug.out output file.

InetConnection.cpp

This file contains the InetConnection class definition for establishing an Internet socket connection (TCP/IP). InetConnection is the base class for wctpConnection (see below).

InetConnection.hpp

This file contains the InetConnection class declaration for establishing an Internet socket connection (TCP/IP). InetConnection is the base class for wctpConnection (see below).

Makefile

This is the make file for the example application, wctpXml_client.  Invoke it with ‘make’ issued from the Linux command line and it will build an executable, wctpXml_client.

UpdateDebug.pl

This is a perl script utility that scans your source code and generates updated DebugLabels.hpp and DebugLabels.cpp files for you. This is handy since there must be an entry in both of those files for each debugging key that occurs in your source code and there can be many of these keys. See the DynaDebug.txt file for a full description.

wctpConnection.cpp

This file contains the wctpConnection class definition for establishing a wctp socket connection (TCP/IP). wctpConnection has InetConnection as a base class. It offers some useful operations regarding encoding, and assumes that the contents being sent/received is WCTP/XML.

wctpConnection.hpp

This file contains the wctpConnection class declaration for establishing a wctp socket connection (TCP/IP). wctpConnection has InetConnection as a base class. It offers some useful operations regarding encoding, and assumes that the contents being sent/received is WCTP/XML.

wctpXml_client.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).

Building

To build the example application, wctpXml_client, do the following:

1.       build the wctpXml (and xmlparse) libraries.

2.       cd to the wctpXml/example directory.

3.       issue the command ‘make’.

Executing

To run the wctpXml_client, issue the following command:

wctpXml_client -h <host> -p <port> -a <path> [-r <recipient>]

The first argument, wctpXml_client, 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, wctpXml_client will generate a wctp-SubmitClientMessage request and display the resulting wctp-SubmitClientResponse. If it is not present, wctpXml_client will generate a wctp-VersionQuery request and display the resulting wctp-VersionResponse.

For example, to generate a wctp-VersionQuery:

wctpXml_client -h 123.234.12.23 -p 80 -a /wctp

or, to generate a wctp-SubmitClientMessage to recipient 1234567:

wctpXml_client -h 123.234.321.2 -p 80 -a /wctp –r 1234567

Debugging

The wctpXml_client supports dynamic debugging so that it is easier to see what is going on internally, particularly in cases where the example is not working as expected. This dynamic debugging is only enabled if the macro DYNADEBUG is defined at compile time (the option –DDYNADEBUG is on the compile line in your make file). For full details of the dynamic debugging, see the DynaDebug.txt file.  Once you are familiar with this model, you can turn debugging on by defining DYNADEBUG at compile time. You can then add one or more lines to the debug.cfg file with the key that corresponds to the code you wish to monitor.  Do this before you execute wctpXml_client, since it exits almost immediately.  In a more complex application, you can make these changes during the execution and turn specific debugging on and off without restarting your application. The following table shows the keys defined in wctpXml_client for dynamic debugging, and describes the output obtained by turning each of them on.

Debugging Key

(from DebugLabels.hpp)

Output

WCTP_XML_CLIENT_DEBUG

Traces the application execution at the highest level – the functions in wctpXml_client.cpp.

INET_CONN_DEBUG

Traces all aspects of the communications with the server: connecting, looking up the IP address, reading/writing, and so on.

INET_CONN_POLL_DEBUG

Shows each time the client “hangs” on the connection to the server using a select( ) call.

Code Review

wctpXml_client 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 wctpConnection class operation open_conn( )

5.       write the WCTP/XML request string to the WCTP server using the wctpConnection class operation write_xml( )

6.       read the WCTP/XML response string from the WCTP server using the wctpConnection class operation read_xml( )

7.       close the connection to the WCTP server using the wctpConnection 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( ).