Copyright © 2001 WorldCom, Inc.
The wctpXml library provides C++ classes for generating and parsing the wctp-Operations needed for communication with a WCTP gateway. Each of the classes is covered below, with an explanation of its corresponding wctp-Operation. For information on using these classes, please see How To Use wctpXml.
Each of the utility and base classes used in wctpXml is listed below with its corresponding purpose. Some of the utility classes, such as XString and TStack, are useful and you may wish to use them elsewhere in your applications. Otherwise, though, these classes are mentioned here for reference purposes only – you should not need to instantiate any of these classes to use wctpXml. You will normally work directly with the wctpXmlXXX classes in the next section.
|
Utility/Base Class |
Purpose |
|
EncodeUtil |
This class provides methods for encoding and decoding using the BASE64 and UUENCODE formats. Used by wctpXmlTransparentData for encoding/decoding binary data. |
|
TStack |
This class is a non-intrusive, indirect, expandable, non-memory owning, Traversable Stack, implemented using a Doubly Linked list. It is used in many classes to hold collections of other class instances. |
|
wctpXml |
The wctpXml.hpp file contains the common enums and typedefs for the project. The class contains only common operations for converting enums/typedefs into printable strings, and vice-versa. These operations are used in parsing/generating WCTP text. |
|
wctpXmlOperation |
This is the base class for all of the classes that correspond to wctp elements. It provides the basic parsing/generation functions for the WCTP/XML, as well as access to the wctp-Operation attributes (the wctpVersion and wctpToken attributes, and the DTD file in the SYSTEM portion of the DOCTYPE element). |
|
XmlContext |
This class holds the current “context” for generating WCTP/XML code – primarily indentation and other formatting details. Each of the wctpXmlXXX classes uses an XmlContext instance during assembly. |
|
XmlNode |
This class is used as a node in the tree generated by parsing XML using the expat library. For more information on nodes, see the documentation on expat. |
|
Xstring |
This class is a lightweight, dynamically allocating string. It is used in many classes to hold variable-length strings, and to pass them as arguments to operations. |
Each wctpXml utility/base class XXX shown above consists of two source code files – a header file (wctpXml/inc/XXX.hpp), and an implementation file (wctpXml/src/XXX.cpp). The header file contains the class declaration and any required type definitions or enumerations. The implementation file contains the actual class definitions (source code).
wctpXmlOperation implements the XML parsing and generation, using the wctpXml utility class and the expat non-validating XML parser. Each wctpXml C++ class wctpXmlXXX shown in the Request and Response Classes section below inherits from wctpXmlOperation (the common base class), as do those in the Sub-Element Classes section.
For each wctpXml class wctpXmlXXX (whether it is a request/response or a support class), there are two source code files – a header file (wctpXml/inc/wctpXmlXXX.hpp), and an implementation file (wctpXml/src/wctpXmlXXX.cpp). The header file contains the class declaration and any required type definitions or enumerations. The implementation file contains the actual class definitions (source code).
Each of the wctpXmlXXX classes supports operations to fill and retrieve values for the XML attributes as specified in the WCTP 1.1 Protocol Specification. For each attribute Y identified in the specification, the class offers two operations: GetY( ) to retrieve the value, and SetY( ) to set the value. Because of this consistency, the individual attributes will not be covered in the class discussions below. For details of the use and valid values for any attribute, see the WCTP 1.1 Protocol Specification document.
Whenever you access an instance of a class representing a sub-element (asking for a wctpXmlFailure from a wctpXmlConfirmation, for example) via a GetXXX( ) that returns a pointer to the sub-element class (in this example, calling GetFailure( ) to get a pointer to the wctpXmlFailure), DO NOT delete the pointer when you are done using it. Only call delete( ) on instances of classes that you instantiated using new( ).
In any wctpXmlXXX class where there is an optional sub-element of the class wctpXmlYYY, there will be a corresponding HoldYYY( ) operation. Call this operation to have the class instantiate an instance of the sub-element class. If this operation is not called first, calls to GetYYY( ) will return a NULL pointer. For example, a wctpXmlStatusInfo object can contain a wctpXmlFailure or not. If you instantiate a wctpXmlStatusInfo object and wish to set it to have a wctpXmlFailure, call HoldFailure( ), followed by GetFailure( ) to retrieve a pointer to the newly instantiated sub-element. Use the pointer to set the attributes of the wctpXmlFailure (by providing an error code, error text, and so on). The wctpXmlFailure object is owned by the wctpXmlStatusInfo object, and it will be destroyed when the wctpXmlStatusInfo object is destroyed.
In any wctpXmlXXX class where there can be more than one sub-element of the class wctpXmlYYY, there will be a corresponding AddYYY( ) operation which instantiates an instance of the sub-element class and returns a pointer to it. For example, a wctpXmlPollForMessages object can contain zero or more wctpXmlMessageReceived objects. If you instantiate a wctpXmlPollForMessages object and wish to set it to have a wctpXmlMessageReceived, call AddMessageReceived( ) which returns a pointer to the newly instantiated sub-element. Use the pointer to set the attributes of the wctpXmlMessageReceived. The wctpXmlMessageReceived object is owned by the wctpXmlPollForMessages object, and it will be destroyed when the wctpXmlPollForMessages object is destroyed.
Each of the wctpXml request/response classes is listed below with its corresponding wctp-Operation. To use this table, find the WCTP operation to be implemented in the left column, and look across to the right column to determine the name of the class to instantiate. Each wctpXml C++ class wctpXmlXXX shown below inherits from wctpXmlOperation (the common base class – see the preceding section on Utility and Base Classes).
|
WCTP Operation |
wctpXml Class to Use |
|
wctp-ClientQuery |
wctpXmlClientQuery |
|
wctp-ClientQueryResponse |
wctpXmlClientQueryResponse |
|
wctp-Confirmation |
wctpXmlConfirmation |
|
wctp-LookupSubscriber |
wctpXmlLookupSubscriber |
|
wctp-LookupResponse |
wctpXmlLookupResponse |
|
wctp-MessageReply |
wctpXmlMessageReply |
|
wctp-PollForMessages |
wctpXmlPollForMessages |
|
wctp-PollResponse |
wctpXmlPollResponse |
|
wctp-StatusInfo |
wctpXmlStatusInfo |
|
wctp-SubmitClientMessage |
wctpXmlSubmitClientMessage |
|
wctp-SubmitClientResponse |
wctpXmlSubmitClientResponse |
|
wctp-SubmitRequest |
wctpXmlSubmitRequest |
|
wctp-VersionQuery |
wctpXmlVersionQuery |
|
wctp-VersionResponse |
wctpXmlVersionResponse |
Class wctpXmlClientQuery
Request from a Transient Client
Class wctpXmlClientQuery is the encapsulation of a wctp-ClientQuery element. Only a WCTP client can send this request, and it can only send it to a WCTP server. It is used to determine the current “status” of a message that was previously sent to the server using wctp-SubmitClientMessage. A wctpXmlClientQuery contains no sub-elements, only key attributes needed to identify the original message.
Class wctpXmlClientQueryResponse
Response from a Server
Class wctpXmlClientQueryResponse is the encapsulation of a wctp-ClientQueryResponse element. This response element can only be received from a WCTP server in response to a wctp-ClientQuery request. A wctpXmlClientQueryResponse contains one or more wctpXmlClientMessages (each of which corresponds to a notification of an event such as delivery or a reply), or it contains a wctpXmlNoMessages (meaning that the request succeeded but that there are no informational messages to download at this time), or it contains a wctpXmlFailure (corresponding to a failure of the request). To determine which, call GetClientQueryResponseType( ). If it returns WCTP_XML_CLIENT_MESSAGE, then a subsequent call to NumClientMessage( ) will return the actual number of wctpXmlClientMessage objects that can be retrieved using GetClientMessage(pos) where pos is a zero-based index (running from 0 to num – 1). If it returns WCTP_XML_NO_MESSAGES, then a subsequent call to GetNoMessages( ) will return a pointer to a wctpXmlNoMessages object, and NumMessage( ) should return zero. If it returns WCTP_XML_FAILURE, then a subsequent call to GetFailure( ) will return a pointer to a wctpXmlFailure object.
Class wctpXmlConfirmation
Response from a Server
Class wctpXmlConfirmation is the encapsulation of a wctp-Confirmation element. This generic response element can be received from a WCTP server in response to a number of requests. A wctpXmlConfirmation contains either a wctpXmlFailure or a wctpXmlSuccess (corresponding to the failure or success of the request). To determine which, call GetConfirmationType( ). If it returns WCTP_XML_FAILURE, then a subsequent call to GetFailure( ) will return a pointer to a wctpXmlFailure object. If it returns WCTP_XML_SUCCESS, then a subsequent call to GetSuccess( ) will return a pointer to a wctpXmlSuccess object.
Class wctpXmlLookupSubscriber
Request from an Enterprise Host Client
Class wctpXmlLookupSubscriber is the encapsulation of a wctp-LookupSubscriber element. Only a WCTP enterprise host client should send this request, and only send it to a WCTP server. Since the immediate response to the wctp-LookupSubscriber is a wctp-Confirmation acknowledging the receipt of the request, transient clients cannot obtain the wctp-LookupResponse (it is POSTed by the carrier to the originator address in the request). A wctpXmlLookupSubscriber contains a wctpXmlOriginator (identifying the requestor, to whom the wctp-LookupResponse will be POSTed), a wctpXmlLookupMessageControl, and a wctpXmlRecipient (identifying the subscriber for whom information is being requested). To access the instances of these classes, call GetOriginator( ), GetLookupMessageControl( ), and GetRecipient( ) respectively.
Class wctpXmlLookupResponse
Received from a Server via a POST
Retrieved in wctp-PollForMessages
Class wctpXmlLookupResponse is the encapsulation of a wctp-LookupResponse element. Only a WCTP enterprise host client can receive this element, and then only from a WCTP server an asynchronous response to a wctp-LookupSubscriber request. A wctpXmlLookupResponse contains a wctpXmlOriginator (identifying the subscriber for whom the information is valid), a wctpXmlRecipient (identifying the original requestor from the wctp-LookupSubscriber). To access the instances of these classes, call GetOriginator( ) and GetRecipient( ) respectively. It also contains either a wctpXmlLookupData (containing information about the subscriber) or a wctpXmlFailure (corresponding to a failure of the request). To determine whether the wctpXmlLookupResponse contains a wctpXmlLookupData or a wctpXmlFailure, call GetLookupResponseType( ). If it returns WCTP_XML_LOOKUP_DATA, then a subsequent call to GetLookupData( ) will return a pointer to a wctpXmlLookupData element. If it returns WCTP_XML_FAILURE, then a subsequent call to GetFailure( ) will return a pointer to a wctpXmlFailure object.
Class wctpXmlMessageReply
Request from a Client or
Received from a Server via a POST
Retrieved in wctp-PollForMessages
Class wctpXmlMessageReply is the encapsulation of a wctp-MessageReply element. Either a WCTP client or a WCTP server can send this request, representing a new message being sent that is a reply to an earlier message. A WCTP server can initiate this request via a POST or include it in a wctp-PollResponse. A wctpXmlMessageReply contains a wctpXmlResponseHeader (containing the details about the message envelope and delivery) and a wctpXmlPayload (containing the body of the message, or the content). To access the instances of these classes, call GetResponseHeader( ) and GetPayload( ) respectively.
Class wctpXmlPollForMessages
Request from a Client
Class wctpXmlPollForMessages is the encapsulation of a wctp-PollForMessages element. Only a WCTP client can send this request, and only send it to a WCTP server. It represents a request to download any messages being held by the carrier for this poller. A wctpXmlPollForMessages contains zero or more wctpXmlMessageReceived elements (one for each message that was successfully downloaded on the preceding wctp-PollForMessages call). The WCTP server will not download these messages to the poller again once they have been acknowledged in this manner. For each message acknowledgement of this type to add, call AddMessageReceived( ). This will return a pointer to a newly allocated wctpXmlMessageReceived that is contained in the wctpXmlPollForMessages object. Use the operations on the wctpXmlMessageReceived class to fill it before sending the wctpXmlPollForMessages.
Class wctpXmlPollResponse
Response from a Server
Class wctpXmlPollResponse is the encapsulation of a wctp-PollResponse element. This response element can only be received from a WCTP server in response to a wctp-PollForMessages request. A wctpXmlPollResponse contains one or more wctpXmlMessages (each of which corresponds to a message for the poller), or it contains a wctpXmlFailure (corresponding to a failure of the request), or it contains a wctpXmlNoMessages (meaning that the request succeeded but that there are no messages to download at this time). To determine which, call GetPollResponseType( ). If it returns WCTP_XML_MESSAGE, then a subsequent call to NumMessage( ) will return the actual number of wctpXmlMessage objects that can be retrieved using GetMessage(pos) where pos is a zero-based index (running from 0 to num – 1). If it returns WCTP_XML_NO_MESSAGES, then a subsequent call to GetNoMessages( ) will return a pointer to a wctpXmlNoMessages object, and NumMessage( ) should return zero. If it returns WCTP_XML_FAILURE, then a subsequent call to GetFailure( ) will return a pointer to a wctpXmlFailure object.
Class wctpXmlStatusInfo
Received from a Server via a POST
Retrieved in wctp-PollForMessages
Class wctpXmlStatusInfo is the encapsulation of a wctp-StatusInfo element. Only a WCTP server can initiate this request (via a POST or in a wctp-PollResponse), representing the status of a message sent earlier. A wctpXmlStatusInfo contains a wctpXmlResponseHeader (containing the details about the status message) and either a wctpXmlFailure (corresponding to a failure of the request) or a wctpXmlNotification (containing information about the status of the original message). A call to GetResponseHeader( ) will return a pointer to a wctpXmlResponseHeader object. To determine if the wctpXmlStatusInfo object contains a wctpXmlFailure or a wctpXmlNotification, call GetStatusInfoType( ). If it returns WCTP_XML_FAILURE, then a subsequent call to GetFailure( ) will return a pointer to a wctpXmlFailure object. If it returns WCTP_XML_NOTIFICATION, then a subsequent call to GetNotification( ) will return a pointer to a wctpXmlNotification object.
Class wctpXmlSubmitClientMessage
Request from a Client
Class wctpXmlSubmitClientMessage is the encapsulation of a wctp-SubmitClientMessage element. Only a WCTP transient client should send this request, and only send it to a WCTP server. It represents a request to send/deliver a message. A wctpXmlSubmitClientMessage contains a wctpXmlSubmitClientHeader (containing the details about the message envelope and delivery) and a wctpXmlPayload (containing the body of the message, or the content). To access the instances of these classes, call GetSubmitClientHeader( ) and GetPayload( ) respectively.
Class wctpXmlSubmitClientResponse
Response from a Server
Class wctpXmlSubmitClientResponse is the encapsulation of a wctp-SubmitClientResponse element. This response element can only be received from a WCTP server in response to a wctp-SubmitClientMessage request. A wctpXmlSubmitClientResponse contains either a wctpXmlFailure (corresponding to a failure of the request) or a wctpXmlClientSuccess (meaning that the request succeeded and the message will be delivered). To determine which, call GetSubmitClientResponseType( ). If it returns WCTP_XML_FAILURE, then a subsequent call to GetFailure( ) will return a pointer to a wctpXmlFailure object. If it returns WCTP_XML_CLIENT_SUCCESS, then a subsequent call to GetClientSuccess( ) will return a pointer to a wctpXmlClientSuccess object.
Class wctpXmlSubmitRequest
Request from an Enterprise Host Client
Received from a Server via a POST
Retrieved in wctp-PollForMessages
Class wctpXmlSubmitRequest is the encapsulation of a wctp-SubmitRequest element. Only a WCTP enterprise host client should send this request to a WCTP server. A WCTP server can also initiate this request via a POST or include it in a wctp-PollResponse. It represents a request to send/deliver a message. A wctpXmlSubmitRequest contains a wctpXmlSubmitHeader (containing the details about the message envelope and delivery) and a wctpXmlPayload (containing the body of the message, or the content). To access the instances of these classes, call GetSubmitHeader( ) and GetPayload( ) respectively.
Class wctpXmlVersionQuery
Request from a Client
Class wctpXmlVersionQuery is the encapsulation of a wctp-VersionQuery element. Only a WCTP client should send this request, and only send it to a WCTP server (although this may be extended in WCTP 2.0 to allow servers to initiate this request against enterprise hosts). It represents a request to list the valid WCTP support for the server. A wctpXmlVersionQuery contains no sub-elements, only key attributes needed to identify the request.
Class wctpXmlVersionResponse
Response from a Server
Class wctpXmlVersionResponse is the encapsulation of a wctp-VersionResponse element. This response element can only be received from a WCTP server in response to a wctp-SubmitClientMessage request (although this may be extended in WCTP 2.0 to allow enterprise host clients to respond to servers). A wctpXmlVersionResponse may contain a wctpXmlContactInfo (corresponding to the contact information for the responder, in case the requestor needs additional information or assistance in making the WCTP connection work). It also contains either a wctpXmlFailure (corresponding to a failure of the request) or one or more wctpXmlDTDSupport elements (one for each WCTP DTD that the responder supports). To determine which, call GetVersionQueryResponseType( ). If it returns WCTP_XML_VERSION_CONTACT_INFO, then a subsequent call to GetVersionContactInfo( ) will return a pointer to a wctpXmlVersionContactInfo object. If it returns WCTP_XML_VERSION_DTD_SUPPORT, then a subsequent call to NumVersionDTDSupport( ) will return the actual number of wctpXmlVersionDTDSupport objects that can be retrieved using GetVersionDTDSupport(pos) where pos is a zero-based index (running from 0 to num – 1).
A support class is defined to be a class that encapsulates a WCTP sub-element class that is only used as a component of a wctp-Operation element (although possibly several layers down). Each of the wctpXml support classes is listed below with its corresponding WCTP element. To use this table, find the WCTP element to be implemented in the left column, and look across to the right column to determine the name of the class to instantiate. Each wctpXml C++ class wctpXmlXXX shown below inherits from wctpXmlOperation (the common base class – see the section on Utility and Base Classes).
|
WCTP Element |
wctpXml Class to Use |
|
wctp-Alphanumeric |
wctpXmlAlphanumeric |
|
wctp-Choice |
wctpXmlChoice |
|
wctp-ClientMessage |
wctpXmlClientMessage |
|
wctp-ClientMessageControl |
wctpXmlClientMessageControl |
|
wctp-ClientMessageReply |
wctpXmlClientMessageReply |
|
wctp-ClientOriginator |
wctpXmlClientOriginator |
|
wctp-ClientResponseHeader |
wctpXmlClientResponseHeader |
|
wctp-ClientStatusInfo |
wctpXmlClientStatusInfo |
|
wctp-ClientSuccess |
wctpXmlClientSuccess |
|
wctp-Failure |
wctpXmlFailure |
|
wctp-LookupData |
wctpXmlLookupData |
|
wctp-LookupMessageControl |
wctpXmlLookupMessageControl |
|
wctp-MCR |
wctpXmlMCR |
|
wctp-Message |
wctpXmlMessage |
|
wctp-MessageControl |
wctpXmlMessageControl |
|
wctp-MessageReceived |
wctpXmlMessageReceived |
|
wctp-MessageText |
wctpXmlMessageText |
|
wctp-NoMessages |
wctpXmlNoMessages |
|
wctp-Notification |
wctpXmlNotification |
|
wctp-Originator |
wctpXmlOriginator |
|
wctp-Payload |
wctpXmlPayload |
|
wctp-Recipient |
wctpXmlRecipient |
|
wctp-ResponseHeader |
wctpXmlResponseHeader |
|
wctp-SubmitClientHeader |
wctpXmlSubmitClientHeader |
|
wctp-SubmitHeader |
wctpXmlSubmitHeader |
|
wctp-Success |
wctpXmlSuccess |
|
wctp-TransparentData |
wctpXmlTransparentData |
|
wctp-ContactInfo |
wctpXmlVersionContactInfo |
|
wctp-DTDSupport |
wctpXmlVersionDTDSupport |