How to Use wctpXml

Copyright © 2001 WorldCom, Inc.

Using wctpXml in a Linux Environment

Installing

Once you have downloaded the wctpXmlLinux.zip file, extract the files to a directory of your choosing.  The result will be the directory structure for Linux. 

Building

This structure is set up to build two static libraries, libWctpXml.a and libexpat.a, with which you will link to create your final executable.  To do this, perform the following steps:

  1. create the expat library libexpat.a by changing directory to wctpXml/expat and issuing the command:

make

  1. create the wctpXml library libWctpXml.a by changing directory to wctpXml and issuing the command:

make

Makefile Modifications

Make the following changes to your makefile in order to compile and link using wctpXml:

  1. modify the compile invocation to provide include directory locations (-I options) for the wctpXml/inc and wctpXml/expat/xmlparse directories (the location of the header files).  For example, if your makefile resides in a directory that is collocated with the wctpXml directory, add the following options to your compile command:

-I../wctpXml/inc –I../wctpXml/expat/xmlparse

  1. modify the compile invocation to provide library directory locations (-L options) for the wctpXml and wctpXml/expat/xmlparse directories. For example, if your makefile resides in a directory that is collocated with the wctpXml directory, add the following options to your link command:

-L../wctpXml –L../wctpXml/expat/xmlparse

  1. modify the link invocation to identify the libraries needed (-l options): libWctpXml.a and libexpat.a. For example, if your makefile resides in a directory that is collocated with the wctpXml directory, add the following options to your link command:

-lWctpXml –lexpat

 

Using wctpXml in a Windows Environment

Installing

Once you have downloaded the wctpXmlVC++.zip file, extract the files to a directory of your choosing.  The result will be the directory structure for Windows.

Project Modifications

This structure is set up to build a static library, wctpxml.lib, with which you will link to create your final executable.  The expat structure is set up to build a Dynamic Link Library (DLL), xmlparse.dll, along with a library (xmlparse.lib) with which you will link.  To modify your project file to create these items as part of a build, perform the following steps:

  1. add the following Visual C++ projects to your application’s workspace: wctpXml/expat/gennmtab/gennmtab.dsp, wctpXml/expat/xmlparse/xmlparse.dsp, and wctpXml/bin/wctpXml.dsp. NOTE: the xmlparse.dsp project, as defined for expat and provided here, builds the XML library as a DLL.  If you do not wish to use/create/distribute xmlparse.dll, open xmlparse.dsp using Visual C++ and modify the project settings to create only a static library instead.
  2. define dependencies in your workspace such that your project depends on wctpXml, wctpXml depends on xmlparse, and xmlparse depends on gennmtab.
  3. modify the project settings for your project:
    1. Set your project to be the active project (choose “Project/Set Active Project” from the main menu).
    2. Select “Project/Settings” from the main menu to display your project settings.
    3. Select the “All Configurations” entry in the drop-down list box on the left.
    4. On the “C/C++” tab, choose “Preprocessor” from the drop-down list, and add the paths to the wctpXml\inc and wctpXml\expat\xmlparse directories to the “Additional include directories” box.   These paths may be relative or absolute paths on your machine.
    5. On the “Link” tab, choose “Input” from the drop-down list, and add the libraries WctpXml.lib and xmlparse.lib to the “Object/library modules” box.
    6. Select each configuration from the configuration list on the left, and for each one enter the appropriate library paths for the libraries from the previous step.  Note that for a “debug” configuration, enter the paths to the debug versions of the libraries (wctpXml\bin\debug and wctpXml\expat\xmlparse\debug), and for a “release” enter the paths to the release versions of the libraries (wctpXml\bin\release and wctpXml\expat\xmlparse\release).  Note that the corresponding expat DLL files are in wctpXml\expat\bin (release) and wctpXml\expat\dbgbin (debug).
    7. Save the changes to your project settings.
  4. create all of the libraries by selecting your project and selecting “Build/Rebuild All” from the menu.

 

Using the wctpXml Classes

Once you have built the libraries successfully, you must generate code in your application to use the wctpXml classes.  Each wctpXml class with a name of the form wctpXmlXXXX encapsulates one WCTP element supported in WCTP 1.1.  To generate the WCTP/XML code for a wctp-SubmitClientMessage, for example

  1. instantiate a wctpXmlSubmitClientMessage object
  2. fill it using the SetNNN( ) operation for each attribute
  3. obtain a pointer to each sub-element MMM as necessary using the HoldMMM( ) and GetMMM( ) operations, and fill their attributes as desired
  4. request the appropriate string from it using AssembleRequestString( )
  5. wrap the request string in an appropriate HTTP header
  6. pass the HTTP-wrapped request string to the server
  7. collect the response from the server as a string, and verify that no HTTP error occurred
  8. instantiate an object of the appropriate response type (for an wctpXmlSubmitClientMessage object we need a wctpXmlSubmitClientResponse)
  9. put the response string into the wctpXmlSubmitClientResponse using Parse( )
  10. query the wctpXmlSubmitClientResponse object for its contents, checking for success or failure (in this case, GetSubmitClientResponseType( ) = = WCTP_XML_FAILURE or WCTP_XML_CLIENT_SUCCESS) and accessing the desired attributes

Complete demonstrations of this process can be found in the examples included with this library: the Linux example application, wctpXml_client, and the Win32 example application, w32Example .