Framework EDI ISAPI Extension


AS2 ISAPI Extension

The Framework EDI AS2 ISAPI is an HTTP ISAPI extension that provides the following capability to the Framework EDI client:

Process a file using a custom ActiveX component on a remote server.
Maintains a HTTP connection between the client and the remote server while the ActiveX component is processing the file.
Allows an ActiveX component on the remote server to send back a file to the client on the same HTTP connection that the client connected with the server.
Allows an ActiveX component on the remote server to process a file after the HTTP connection session has completed with the client, and the client has disconnected from the server.

NOTE: For the purpose of brevity, throughout this document all references to ISAPI or ISAPI DLL refers only to the Framework EDI/AS2 ISAPI component or DLL, and not to a general reference of any ISAPI component or ISAPI itself.

ISAPI Extension Operation

The order in which the ISAPI Extension processes the file as soon as it is sent from the client is as follows:

The HTTP server captures the stream of data from the client and forwards it to the ISAPI extension.
The ISAPI extension then saves the file to the target path specified by the client.
The ISAPI extension then launches an ActiveX component specified by the client, and then passes the full file path name of the file, that it has saved to disk, to a "processing" method in the ActiveX component.
The extension waits and keeps the connection open while the ActiveX component is processing the file.
After the ActiveX component has completed processing the file, the ISAPI extension calls a "result" method in the ActiveX component.
If the string returned by the "result" method is a file, the ISAPI extension reads the contents of the file and sends back the data to the client as an HTTP response.
The ISAPI extension then notifies the HTTP server to end the session and also to close the connection.
The ISAPI extension then calls a "final" method in the ActiveX component after it has disconnected from the client.

ISAPI Extension DLL

The name of the FREDI ISAPI Extension DLL is "frediAs2Isapi.dll". It is loaded by the HTTP server when it is invoked via a URL. Internally, the FREDI client constructs the URL when it sends a file to the server and when an ISAPI DLL has been specified in the HTTP configuration object interface (ediHttpCfg). Example,

oHttpCfg.IsapiExtension = "frediAs2Isapi.dll"

The URL construct sent to the HTTP server would look something like this:

http://www.somewebsite.com/ frediAs2Isapi.dll?..<query>..

Alternatively, the whole URL construct can be specified as the target path to invoke the ISAPI extension. Please see Query String below.

User defined ActiveX extension

When a client sends a file to the ISAPI extension (via HTTP server), the ISAPI extension will save the file to a target path specified by the client. The extension does not make use of the file it has just captured and saved, but instead passes that task to an ActiveX component. The FREDI client determines what ActiveX component should be used by specifying the program identifier in the HTTP configuration object interface (ediHttpCfg), or specifying it in the ISAPI Extension Console. The ActiveX component should have the following methods, which the ISAPI extension calls in order:

The Process method. This is the first method called by the ISAPI extension when it loads the ActiveX component. This method must exist in the interface.
The Result method. If there is any string value generated as a result of the operation by the Process method above, the value is retrieved by calling this method. Additional operations can be performed here, and in general gives the COM component an opportunity to return a string value. This method is optional and does not have to be specified.
The Final method. At this point the ISAPI has disconnected from the client. If this method is specified, this method is invoked by the ISAPI extension. The call is identical to the Process method, only this is called when the server has disconnected from the client.

Example

For example, if the program ID of the ActiveX component is "IsapiSample.App", and the process method is "ProcFile", and the result method is "ReturnFile", and the final method is "Cleanup", then the sample code snippet on the FREDI client would look something like:

Dim oHttpCfg As Fredi.ediHttpCfg
:
Set oHttpCfg = oTransport.GetHttpCfg
oHttpCfg.IsapiActiveXProgID = "IsapiSample.App"
oHttpCfg.IsapiActiveXRunProc = "ProcFile"
oHttpCfg.IsapiActiveXRetProc = "ReturnFile"
oHttpCfg.IsapiActiveXFinalProc = "Cleanup"
oHttpCfg.IsapiActiveXParam = ""

From the example above, on the server side, there has to be an ActiveX component having an interface with program ID of "IsapiSample.App", and the interface implements the three methods: "ProcFile", "ReturnFile" and "Cleanup". Or, alternatively, these settings can be manually set on the server side using the ISAPI Extension Console. The settings in the ISAPI Extension Console overrides any settings specified in the ediHttpCfg object on the client application.

The Processing Method

The processing method is the first method called by the ISAPI extension after a file has been received. The ISAPI is still connected with the client throughout the duration of the call to the ActiveX method. The method MUST receive two string parameters:

the first parameter receives the file name, and
the second parameter receives any string parameter.

In addition, the method MUST return a numeric value indicating the result of the operation. The syntax of this method is as follows:

<lReturnValue> = <Object>.<MethodName>(<sFileName>,<sAnyString>)

Where:

lReturnValue is the return value of the method. The ISAPI extension will interpret the meaning of the return value as follows:

If the return value is "1" then the method has succeeded and any string returned by the result method is assumed to be a file containing the contents to be sent back.
If the return value is "2" then the method has succeeded and any string returned by the result method is assumed to be a file containing the contents to be sent back, and the file is then deleted by the ISAPI extension.
If the return value is "3" then the method has succeeded and any string returned by the result method is returned back to the client.
All other return value is interpreted as a failure by the method.

Object is the instance of the component.
MethodName is the name of the method to be called by the ISAPI extension.
sFileName is the name of the file to process.
sAnyString is any string passed by the client that may or may not be processed by the component.

The sAnyString is any string that the FREDI client wishes to pass to the ActiveX component. The string is set in the "IsapiActiveXParam" property of the HTTP configuration object. Using the same example above, if the client wished to pass the string"USA=1,EURO=2" then the code snippet would look like:

Dim oHttpCfg as As Fredi.ediHttpCfg
:
Set oHttpCfg = oTransport.GetHttpCfg
oHttpCfg.IsapiActiveXProgID = "IsapiSample.App"
oHttpCfg.IsapiActiveXRunProc = "ProcFile"
oHttpCfg.IsapiActiveXRetProc = "ReturnFile"
oHttpCfg.IsapiActiveXFinalProc = "Cleanup"
oHttpCfg.IsapiActiveXParam = "USA=1,EURO=2"

Example,

Public Function ProcessProc(ByVal sFileName As String, ByVal sParam As String) As Long

m_sErrorMessage = ""

' Return the name of the received file.
m_sReturnFile = sFileName

' Indicates file.
m_lResult = 1

ProcessProc = m_lResult
End Function

The Result Method

If the result method has been specified, the method will be called by ISAPI after it has executed the RUN method. The ISAPI will disconnect with the client after this ActiveX method is executed. The method MUST have no parameters and MUST return a string. The syntax is as follows:

<sResultFile> = <Object>.<MethodName>
Where:

sResultFile is a string returned by the client as a result of the operation by the processing method. The string returned by this method is interpreted by ISAPI as follows:

If the return value returned from the processing method is "1", then the string is taken to be a file and the contents of this file is read and passed back to the client.
If the return value returned from the processing method is "2", then the string is taken to be a file and the contents of this file is read and passed back to the client, and then the file itself is deleted.
If the return value returned from the processing method is "3", then the string is returned back to the client.
If the return value is not "1", "2", or "3" then the string is returned back with the result value.

Object is the instance of the component.
MethodName is the name of the method to be called by the ISAPI extension.

If the result method has not been specified, the ISAPI will disconnect after the Processing method above has been called.

Example,

Public Function ReturnProc() As String

Dim sResult As String

Select Case m_lResult
Case 1 To 3

sResult = m_sReturnFile
Case Else

' A description of the error is returned back to the client. The error
' description is save to the 'm_sErrorMessage' string variable at the
' same time when the error occurs.
sResult = m_sErrorMessage
End Select

ReturnProc = sResult
End Function

The Final Method

If the final method has been specified, the method is what will be called by the ISAPI extension after it has disconnected the session from the client. The syntax is identical to the "processing method". It MUST receive two string parameters: the first parameter receives the file name, and the second parameter receives any string parameter. In addition, the method MUST return a numeric value indicating the result of the operation. The syntax of this method is as follows:

<lReturnValue> = <Object>.<MethodName>(<sFileName>,<sAnyString>)

The sFileName and sAnyString parameters receive the exact same value as what was passed in the processing method.

Example,

Public Function FinalProc(ByVal sFileName As String, ByVal sParam As String) As Long

' TODO: Apply code to process the file after having disconnected from the
' client.

FinalProc = m_lResult
End Function

Query String

The string parameter should not contain any semi-colons because the character is used as a delimiter in the query sent by the client to the ISAPI extension. The syntax of the ISAPI sent by the client is as follows.

PROGID=<activex program ID>;RUN=<activex processing method name>;RET=<activex return method name>;FIN=<activex final method name>;PARAM=<any string param>

An example constructed query can be:

http://www.website.com/frediAs2Isapi.dll/temp/test.txt?PROGID= IsapiSample.App;RUN=ProcFile;RET=ReturnFile;FIN=Cleanup;PARAM=USA=1,EURO=2