SOAP ISAPI Listener Task for IIS

SOAP ISAPI Listener translates HTTP SOAP packets into notifications and sends them to the CIC server. The SOAP ISAPI Listener must be installed on a machine that has IIS installed.

What is a Listener?

A listener receives incoming HTTP messages that contain SOAP requests for some type of service. It parses these messages, decides whether to process the request (based upon threshold values and filter configurations), and dispatches the request to the appropriate method for processing. If the service returns a response, the listener packages the response into an HTTP payload, and sends that back to the client. A listener also handles requests for WSDL information about web services.

The SOAP ISAPI Listener looks at incoming SOAP requests, decides whether requests should be forwarded to CIC to invoke a handler, and forwards appropriate requests to CIC's Notifier subsystem, which in turn calls Interaction Processor to invoke the handler associated with the initiator specified in the incoming message. SOAP ISAPI listener and packages return values from handlers into outgoing HTTP responses, and sends them to the client. If the listener decides not to forward a request to CIC for processing, it returns a fault message (SOAP and/or HTTP) to the requesting client application.

What is ISAPI?

The SOAP ISAPI Listener is sometimes called the SOAP ISAPI DLL, since it is a dynamic link library developed in conformance with Microsoft's Internet Server Application Programming Interface (ISAPI). ISAPI allows developers to extend the functionality of Microsoft's Internet Information Server (IIS). The component that implements the ISAPI Soap Listener task is I3SOAPISAPIU.DLL. This DLL is installed by the Interaction Center SOAP Listener Install to the IIS server of your choice. It translates HTTP requests into notifications and acts as a gatekeeper to prevent denial of service attacks. An ISAPI DLL is not a COM DLL. To invoke an ISAPI DLL, it must be explicitly referenced in a HTTP header. For example:

http://www.foo.com/virtual_directory_name/I3SOAPISAPIU.DLL

The virtual directory name is optional, so long as the server can resolve the location of the DLL.

What is an endpoint?

SOAP invokes methods at HTTP endpoints. An endpoint is a URL that uniquely identifies a namespace URI (Universal Resource Indicator), and the name of the method to execute (known as the NCName). Consider the following endpoint:

uri:my-calculator#Add"

The URI namespace (my-calculator) identifies the code module that contains the method to be called (Add), just as an interface name scopes a method in Java, CORBA, or COM. The namespace and the method name are separated by a pound sign.

When a SOAP request is transported to invoke the method, the endpoint name is passed in the SOAPMethodName header of the HTTP POST request. Consider the following sample HTTP header:

POST /objectURI HTTP/1.1

Host: www.foo.com

SOAPMethodName: urn:foo.com:my-calculator#Add

Content-Type: text/xml

Content-Length: nnnn

The HTTP header indicates that the Add method (from the urn:foo.com:my-calculator namespace) should be invoked against the endpoint identified by http://www.foo.com/objectURI.. The rest of the HTTP request is an XML document that contains additional information needed to invoke the request, such as parameters passed to the method. The server-side software that receives the request (e.g. the SOAP ISAPI Listener) is responsible for processing the request. Unlike other RPC protocols, SOAP doesn't define specific actions that must occur when a request is received. It leaves the implementation details to the process running at the endpoint. See http://www.w3.org/TR/REC-xml-names/