IHttpProtocolProvider Interface

Article
12/03/2008

Provides a framework for developing a custom HTTP-based delivery protocol.

Namespace: Microsoft.SqlServer.NotificationServices
Assembly: Microsoft.SqlServer.NotificationServices (in microsoft.sqlserver.notificationservices.dll)

Syntax

'Declaration
Public Interface IHttpProtocolProvider

public interface IHttpProtocolProvider

public interface class IHttpProtocolProvider

public interface IHttpProtocolProvider

public interface IHttpProtocolProvider

Remarks

This interface provides a framework for developing a custom HTTP-based delivery protocol. Because HTTP-based delivery protocols are common candidates for custom development, this interface is provided to help simplify delivery protocol development. The IDeliveryProtocol interface is to be used for custom delivery protocols that are not HTTP based, or for HTTP-based delivery protocols that require more flexibility than IHttpProtocolProvider provides.

The IHttpProtocolProvider interface provides the following methods:

Initialize allows the delivery protocol to be initialized by the distributor.
FormatEnvelope allows the distributor to pass formatted notification data to the delivery protocol, which then uses this information to create the HTTP envelope.
ProcessResponse allows the delivery protocol to receive and process the HTTP response from the server.
Close allows the distributor to make the delivery protocol release any resources it is using and prepares it for shutdown.

The sequence of calls begins with Initialize, followed by a pair of FormatEnvelope and ProcessResponse calls, one pair for each message to be sent. Close is the last method in the sequence to be called. After Close has returned, FormatEnvelope and ProcessResponse are not called again unless the calling sequence is started over with a new call to Initialize.

The IHttpProtocolProvider interface works in conjunction with the internal HttpExtension class provided by Notification Services. This class wraps most of the basic functionality required when implementing an HTTP-based delivery protocol, including issuing requests and receiving responses from an HTTP server. The developer only needs to create the message envelope and process the HTTP response, using the methods that the IHttpProtocolProvider interface provides.

The distributor does not enforce any time-outs on the IHttpProtocolProvider methods. The delivery protocol classes that provide the implementations are considered to be trusted, tested code. If any of the methods stop responding, then the distributor thread that calls them stops responding. If this happens on enough threads, distributor operation might halt.

To create a custom delivery protocol that implements this interface, you must create a class that implements IHttpProtocolProvider and then create the methods inherited from the interface within this class. Finally, you must code the functionality for these methods that is appropriate for your application.

When developing a custom protocol using HTTP, make sure to guard against unauthorized posts. The following are some example techniques you can use to restrict unauthorized use:

If your delivery channel and receiving agent can share a secret key then that key can be used to generate an SHA1 hash. For more information, see "Ensuring Data Integrity with Hash Codes."
Configure IIS to deny anonymous requests and accept only Microsoft Windows authentication. When your application posts notifications, check the requesting user before accepting the notifications.
If your posts will always coming from the same computer, configure IIS to accept requests only from that computer's IP address.

For more information about developing a custom delivery protocols, see Developing a Custom Delivery Protocol.

Example

Use the following interface declaration to start your HTTP-based custom delivery protocol.

public interface IHttpProtocolProvider
{
    void Initialize(StringDictionary channelArguments);
    String FormatEnvelope(
                StringDictionary protocolFields,
                String requestBody);
    Boolean ProcessResponse(
                HttpStatusCode httpResponseCode,
                String responseBody,
                Boolean postSuccess);
    void Close();
}

In the following code example, the HTTP delivery protocol uses an XSLT file in combination with the protocol fields to build an envelope:

using System;
using System.Collections.Specialized;
using System.Text;
using System.Net;
using System.Xml;
using System.IO;
using Microsoft.SqlServer.NotificationServices;

namespace AdventureWorks.Notifications.HttpDeliveryProtocol
{
    public class SoapProtocol: IHttpProtocolProvider
    {

        public SoapProtocol()
        {
            // Add constructor logic here if required.
        }
        
        // Implement the IHttpProviderProtocol.Initialize method.
        public void Initialize(StringDictionary channelArguments)
        {
            // Process initialization parameters
            // if any are necessary.
        }

        // Implement the IHttpProviderProtocol.FormatEnvelope method.
        public string FormatEnvelope(StringDictionary protocolFields,
            string requestBody)
        {
            // Use a StringBuilder, a StringWriter, and
            // an XmlTextWriter to create the XML string.
            StringBuilder envelopeBuilder = new StringBuilder();
            StringWriter  envelopeWriter =
                new StringWriter(envelopeBuilder);
            XmlTextWriter xmlWriter = new 
                      XmlTextWriter(envelopeWriter);
            // Create the envelope.
            xmlWriter.WriteStartElement("soap:envelope");
            // Create the header.
            xmlWriter.WriteStartElement("soap:header");
            xmlWriter.WriteStartElement("username");
            xmlWriter.WriteString(protocolFields["userName"]);
            xmlWriter.WriteEndElement();
            xmlWriter.WriteStartElement("password");
            xmlWriter.WriteString(protocolFields["password"]);
            xmlWriter.WriteEndElement();
            xmlWriter.WriteEndElement();
            // Create the body.
            xmlWriter.WriteStartElement("soap:body");
            xmlWriter.WriteString(requestBody);
            xmlWriter.WriteEndElement();
            // Close the envelope.
            xmlWriter.WriteEndElement();

            string envelope = envelopeBuilder.ToString();

            xmlWriter.Close();

            return envelope;
        }

        // Implement the IHttpProviderProtocol.ProcessResponse method.
        public bool ProcessResponse(HttpStatusCode statusCode,
            string responseBody,
            bool postSuccess)
        {
            if (postSuccess)
            {
                return postSuccess;
            }
            else
            {
                return(false);
                // You could log the responseBody info here.
            }
        }

        // Implement the IHttpProviderProtocol.Close method.
        public void Close()
        {
            // Release any system resources here.
        }
    }
}

Platforms

Development Platforms

For a list of the supported platforms, see Hardware and Software Requirements for Installing SQL Server 2005.

Target Platforms