. A standard browser can view the SOAP message you create. For example, Figure 11-2 shows the output from the sample code we looked at earlier. Since we didn’t create an XSL file for this example, the browser uses the default template. This template will show you the content of the SOAP message with keywords and content highlighted in a variety of colors. Normally, you’d pass the SOAP response message to a client side application for interpretation and display. Note that you can click the “-” (minus signs) next to the various entries and collapse them to gain an overview of the message.

Figure 11-2: Internet Explorer versions 5.5 and above can display SOAP messages in a simple format. Browser Alert

Now that you have a taste of what SOAP is like, you might want to view the SOAP specification. The current specification, as of this writing, is version 1.1. You’ll find it at http://static.userland.com/xmlRpcCom/soap/SOAPv11.htm (among other places). Not only will the specification fill you in on additional details, but you’ll also see some example messages that contain the HTTP header, as well as the SOAP message. I chose to concentrate on just the SOAP portion of the message in my example listings.

Now that you have a summary of the SOAP message content, let’s look at some particulars you’ll need when working with SOAP. The following sections will fill you in on some technical details needed to understand the SOAP message fully. The first section tells you about the SOAP data transfer requirements as opposed to those supported by HTTP. The second section will tell you about a Web site that allows you to test your SOAP knowledge. The third section will explore SOAP fault messages. Finally, the fourth section will help you understand the HTTP Extension Framework.

HTTP and the SOAP Transfer SOAP is essentially a one-way data transfer protocol. While SOAP messages often follow a request/response pattern, the messages themselves are individual entities. SOAP doesn’t

link the messages in any way. This means that a SOAP message is stand-alone—it doesn’t rely on the immediate presence of a server, nor does the sender expect a response when a request message contains all of the required information. For example, some types of data entry may not require a response since the user is inputting information and may not care about a response. The envelope in which a SOAP message travels, however, may provide more than just a one-way transfer path. For example, when a developer encases a SOAP message within an HTTP envelope, the request and response both use the same connection. HTTP creates and maintains the connection; SOAP has nothing to do with the connection. Consequently, the connection follows the HTTP way of performing data transfer, using the same techniques as a browser uses to request Web pages for display.

Testing Your SOAP Knowledge Microsoft recently made two Web sites available to check your SOAP messages. The first accepts SOAP messages, parses them, and provides a check of their validity. You’ll find it at http://www.soaptoolkit.com/soapvalidator/. Figure 11-3 shows what this Web site looks like.

Figure 11-3: The SOAP Message Validation site allows you to test your SOAP knowledge and learn about specific message types. As you can see, there are three panes in this display. The SOAP Message Text window contains a message that you want to verify. You can also choose one of the valid or invalid samples from the drop-down list boxes. These samples can teach you quite a bit about SOAP. They provide examples of what you can and can’t do within a message and of the results that you’ll get when performing certain actions. I’ve actually learned how to distinguish some error messages by using this Web site. You don’t need to include the HTTP or XML headers in the SOAP Message Text window, just the SOAP message. The Parsed Version window shows what the message looks like after the SOAP listener parses it. This window doesn’t tell you about the validity of the message, but it does help you understand the XML formatting better. You can use this window to determine if the message is well formed. The tags should form pairs that are easy to see in the pane. The use of text coloring also helps you to distinguish between specific text elements.

The Message Check Results window will show the results of diagnostics the site performs on your SOAP message. You’ll see error messages in places where the SOAP message doesn’t contain required entries or the entry format is incorrect. When all of the error messages are gone, the SOAP message is ready for use. Of course, this still doesn’t mean the SOAP message will do anything. The Web site doesn’t check the validity of the data within the SOAP message. You can create a perfect SOAP message that still doesn’t work because the server-side component expects the data in a different format or even requires other arguments. The second Web site is a generic SOAP listener. You can send a SOAP message to it using an application. The site will test the message much like the Message Check Results window of the SOAP Message Validation site. You’ll find this Web site at http://www.soaptoolkit.com/soapvalidator/listener.asp.

SOAP Fault Messages Sometimes a SOAP request will generate a fault message instead of the anticipated reply. The server may not have the means to answer your request, the request you generated may be incomplete, or bad communication may prevent your message from arriving in the same state as you sent it. There are many reasons that you may receive a SOAP fault message. However, you can generally categorize them into four general areas, as shown in Table 111.

Table 11-1: General SOAP Fault Mes age Clas if ications Message Type

Description

Client

The client generated a request that the server couldn't process for some reason. The most common problem is that the XML format of the SOAP message is incorrect (malformed). Another common problem involves the server not finding the requested component or the client not providing all of the information the server needs to process the message. If the client receives an error message of this type, it must recreate the message and fix the problems of the original. The server usually provides amplifying information if it can determine how the client request is malformed or otherwise in error.

MustUnderstand

This error only occurs when you set the SOAP message mustUnderstand attribute to 1. The error occurs when the client sends a request that the server can't understand or obey for some reason. The server may not understand a request when the client relies on capabilities of a version of SOAP that the server's listener doesn't provide. A server may not obey a client request due to security or other concerns. An upgrade of the listener or server side components will usually help in this situation.

Server

The server couldn't process the message even though the request is valid. A server error can occur for a number of reasons. For example, the server could run out of resources for initializing the requested component. In a complex application environment, the server may rely on the processing of another server that's offline or otherwise inaccessible. The client should definitely resubmit the same request later when this error occurs. The server usually provides amplifying information if it can determine the precise server side error that occurred.

Table 11-1: General SOAP Fault Mes age Clas if ications Message Type

Description

VersionMismatch

SOAP doesn't have a versioning system. It does rely on the namespaces that you define to perform useful work. This error message occurs when the SOAP envelope namespace is either incorrect or missing. As of this writing, you should use a SOAP envelope namespace that points to http://schemas.xmlsoap.org/ soap/envelope/ (as shown in the source code examples in this chapter).

Browser Alert

It’s possible to create other fault categories for SOAP messages. The list in Table 11-2 conforms to the SOAP specification. The only requirement for SOAP fault categories is that they follow the formatting requirements for XML namespaces. A good place to look for additional information about XML namespace formatting is the Namespace in XML document at http://www.w3.org/TR/RECxml-names/ .

Table 11-2: SOAP Fault Mes age Elements Element

Description

faultcode

The faultcode contains the name of the error that occurred. It can use a dot syntax to define a more precise error code. The faultcode will always begin with one of the classifications listed in Table 11-1. Since it's possible to create a list of standard SOAP faultcodes, you can use them directly for processing purposes.

faultstring

The faultstring is a human-readable form of the error specified by the faultcode entry. This string should follow the same format as HTTP error strings. You can learn more about HTTP error strings by reading the HTTP specification at http://www.normos.org/ietf/rfc/rfc2616.txt. A good general rule to follow is to make the faultstring entry short and easy to understand.

faultactor

The faultactor points to the source of a fault in a SOAP transaction. It contains a Uniform Resource Identifier (URI) similar to the one used for determining the destination of the header entry. According to the specification, you must include this element if the application that generates the fault message isn't the ultimate destination for the SOAP message.

detail

The detail element holds specific information about a fault when available. For example, this is the element that you'd use to hold server side component return values. This element is specific to the SOAP message body, which means you can't use it to detail errors that occur in other areas like the SOAP message header. A detail entry acts as an envelope for storing detail sub-elements. Each sub-element includes a tag containing namespace information and a string containing error message information.

When a server returns a fault message, it doesn’t return any data. A typical client fault message contains only fault information. With this in mind, the client side components you create must be prepared to parse SOAP fault messages and return the information to the calling application in such a way that the user will understand the meaning of the fault. The fault envelope resides within the body of the SOAP message. A fault envelope will generally contain a faultcode and faultstring element that tells you which error occurred. All of the other SOAP fault message elements are optional. Table 11-2 provides a list of these elements and tells you how they’re used. Tip You can use the presence or absence of various fault message elements to your advantage when determining the cause of an error. For example, if the faultactor element appears within the fault message, it’s a good bet that the message passed between multiple servers. In some cases, this means that you can eliminate gross formatting errors from your list of things to check, because several machines parsed the message without generating an error. The absence of the detail element, on the other hand, may indicate that the error happened before the component on the server processed the request message. This means there’s a problem with processing the message, rather than a problem with the server side component’s handling of message data. Let’s look more closely at the detail element. As stated, the detail element doesn’t stand alone—it acts as an envelope for additional information. Here’s a typical example of a detail element entry. Couldn't Create Object 429 Notice that detail information begins with a namespace entry. In this case, a component called AddIt that appears in the MyObjects directory on the server had an error. The error message is that it couldn’t create a required object, while the associated error number is 429. The client side SOAP message parser could pass this information to the client application for additional processing. At least the user would have a better idea of what happened and could alert a network administrator to the problem. Of course, the detail element isn’t limited to a single component entry. Every component that has an error could make an entry. For that matter, you might include a single namespace entry for every error that a single component experiences. A component might actually provide several error messages that state an entire list of problems that it experienced in the processing of the SOAP message. For example, rather than return a single message at a time for faulty arguments, the component could parse all of the arguments and return a list of errors that covers all of them.

Writing an ISAPI Extension OK, it’s time to look at our first ISA. In this case, we’ll create a very simple ISAPI extension using the ISAPI Extension Wizard. The whole purpose of this particular example is to get you used to the idea of working with ISAPI and show you some of the techniques you’ll need to make ISAPI work. The example program will accept a string from the client, change it a little, and then display a new page showing the string that the client sent.

Note You’ll find a second example of how to create an ISAPI Extension on the source code CD. Look in the \Chapter 11\DateTime folder for this second example. The \Chapter 11 folder contains the required test Web page. This example shows how to retrieve server data and display it on screen for the user. Install the ISAPI extension on your server using the same techniques found in the “Running the Test Application” section of the chapter.

Creating the Program Shell The following procedure will take you through all the steps required to create the sample ISA. You can use the same procedure to start any ISA extension that you need to create. I’m assuming that you already have Visual C++ running. Browser One of the best places to look for ideas for your own ISAPI Alert extension or filter is freeware produced by other programmers. The alt.comp.freeware newsgroup lists quite a few of these offerings. For example, at the time of this writing, AAIT Incorporated introduced a new freeware product named CGI Expert. It supports the CGI, win-CGI, ISAPI, and NSAPI interfaces simultaneously. Obviously, you’ll want to use freeware products, like any other product, with care. However, they do provide excellent ideas on how to create your own custom extensions when needed—or a solution so you don’t have to do any programming at all. 1. Create a new MFC ISAPI Extension DLL project. The example uses a name of DispStr. You’ll see the ISAPI Extension Wizard dialog box. This same wizard works for both ISAPI Filters and ISAPI Extensions. 2. Select the Object Settings tab. You’ll see a list of choices for your extension or filter, as shown next. This is where you’ll select the various characteristics for your ISA. Notice that there are three main areas to the dialog. You can choose to create a filter by checking the first checkbox and an extension by checking the second checkbox. The third area defines how you’ll link MFC into your application.

3. Check the “Generate a server extension object” option, and clear the “Generate a filter object option.” You’ll want to provide a short, concise statement of what your ISA does in the Extension Description field. The description appears as a string that you can use within the DLL as needed. This description won’t show up in the Properties

dialog when someone opens it for your ISA, so you’ll want to add some additional text to the version information for your DLL as well. 4. Type Display a string from the client. in the Extension Description field. 5. Click Finish. The ISAPI Extension Wizard will create the required program shell for you.

Adding Some Code At this point, we need to do three things to the skeleton that the ISAPI Extension Wizard has created for us to make the extension functional. The first task is to create a parse map for the new function we want to add. You’ll find the parse map near the beginning of the DispStr.CPP file. Listing 11-1 shows the code you’ll need to add to the parse map so that we’ll be able to access the new function from the HTML page. Listing 11-1 //////////////////////////////////////////////////////////////////// / // command-parsing map

BEGIN_PARSE_MAP(CDispStrExtension, CHttpServer) // Our special DisplayStr parse command. ON_PARSE_COMMAND(DisplayStr, CDispStrExtension, ITS_PSTR) ON_PARSE_COMMAND_PARAMS("string='No String Supplied'")

// Default parse command ON_PARSE_COMMAND(Default, CDispStrExtension, ITS_EMPTY) DEFAULT_PARSE_COMMAND(Default, CDispStrExtension) END_PARSE_MAP(CDispStrExtension)

Even though you had to add only two lines of code to make this example work, we’re actually concerned with three lines of code. The ON_PARSE_COMMAND() macro allows you to define a new function. Notice that we supply a function name, the class in which the function is supplied, and the type of parameters the function will use. The ON_PARSE_COMMAND() macro requires a parameter entry, even if you don’t need any parameters to make the function work. Notice that the Default function uses a value of ITS_EMPTY since it doesn’t need any parameters, but that our new function, DisplayStr, has a parameter of ITS_PSTR because it requires a string pointer. That brings us to the ON_PARSE_COMMAND_PARAMS() macro on the next line. You have to tell Visual C++ how to deal with the parameters for your function. For example, if we had wanted to force the user to supply a string value for our function, we’d simply have “string” in the ON_PARSE_COMMAND_PARAMS() macro. Since we don’t absolutely have to have the user supply a string to use our function, I’ve supplied a default value of “No String Supplied.” Be aware that the query will fail if you require a parameter and the user doesn’t supply it. Finally, you need to tell Visual C++ which function to use as a default using the DEFAULT_PARSE_COMMAND() macro. Since the Default function is just fine, in this case, I didn’t change the default setting.

The second change you’ll need to make to the code is to add the function entry to the DispStr.H file. Unless you modify the class specification to include your new function, Visual C++ won’t know anything about it and the DLL won’t compile. Fortunately, all we need is the single line shown in bold in Listing 11-2. I’ve included the surrounding code so that you know where to place the new entry. Listing 11-2 class CDispStrExtension : public CHttpServer { public: CDispStrExtension(); ~CDispStrExtension();

// Overrides public: virtual BOOL GetExtensionVersion(HSE_VERSION_INFO* pVer); virtual BOOL TerminateExtension(DWORD dwFlags);

// TODO: Add handlers for your commands here. // For example:

void Default(CHttpServerContext* pCtxt); void DisplayStr(CHttpServerContext* pCtxt, LPTSTR pszString);

DECLARE_PARSE_MAP() };

As you can see, adding the function call declaration is a simple matter. At this point, though, you may be wondering where the CHttpServerContext* pCtxt part of the declaration came in. We certainly didn’t declare it previously in any of the parse map macros. It turns out that the Web server passes the pCtxt parameter to your function by default. Remember from our previous discussion that the CHttpServer class automatically creates a CHttpServerContext object for every user request. This is where the parameter comes from. What you’re getting is a pointer to the CHttpServerContext object associated with the user’s call to your function. It’s also the way that you keep multiple calls to your function separate—each call has a completely different object associated with it. We need to perform one additional task to make this DLL function: add the function code to the DispStr.CPP file. I added the function code right after the existing Default() function code. Listing 11-3 shows the very short function that I created for this example. There isn’t anything fancy here; the whole purpose is to show you how to put things together. Listing 11-3

void CDispStrExtension::DisplayStr(CHttpServerContext* pCtxt, LPTSTR pszString) { // Start sending information to the new Web page including a default title. StartContent(pCtxt); WriteTitle(pCtxt);

// Display the body of the new page. *pCtxt << _T("

ISAPI Server Extension Example

"); *pCtxt << _T("This was the string you entered:

"); *pCtxt << _T(pszString); *pCtxt << _T("");

// End the display area. EndContent(pCtxt); }

The function itself is easy to figure out. The first thing we do is tell Visual C++ to start a Web page. That’s like adding the and tags to a document. The second thing we do is output a title—just as if we were typing the