The CAS XML interface uses standardized XML formatting and HTTP communications to provide access to NET SatisFAXtion.  The CAS API, with it's assortment of function and data tags, and the rules governing the placement of tags in taglists, is nearly identical regardless of whether an application is written to the CAS ActiveX interface or XML interface.  To a client application these interfaces are very different, but to NET SatisFAXtion taglists are treated the same regardless of their origin.

To create and send taglists, applications can use XML and XMLHTTP APIs provided by Microsoft, or from other development tools.  To simplify development, FaxBack created the CAS XML Script Library that uses Microsoft's APIs to create taglists and connect to NET SatisFAXtion.  With the script library, it is possible to write an application that uses XML and XMLHTTP to communicate with NET SatisFAXtion without installing CAS ActiveX controls on the client computer.  However, CAS ActiveX controls can be installed if desired, and applications can be written that use both the CAS ActiveX and XML interfaces.

When you are ready to send your first fax, make sure that you have examined the CAS Samples on this website.  The CAS Samples provide live demonstrations and example source code for the most commonly used CAS functions.  See the CAS Tags page for a listing of available CAS function and data tags.

Additional CAS XML documentation can be found in our knowledge base here.

Working with Taglists

With the CAS XML interface, CAS tags are represented as XML elements, and CAS taglists are a concatenation of CAS XML elements.  XML taglists have all of the benefits of XML formatting, by being text-based and easily readable.  Because of the straightforward format of XML, taglists can be constructed by simply concatenating text strings, or they can be read from files that were created with a text editor.  For example, the following CAS XML taglist is all that is needed to retrieve all fax port information from a fax server:

<CAS>
 <DOMAIN_NAME>\\CASDEV\NETSATISFAXTION</DOMAIN_NAME>
 <REMOTE_LOGON_NAME>NETSATISFAXTION</REMOTE_LOGON_NAME>
 <PROTOCOL>2</PROTOCOL>
 <TAGLIST>
  <GET_PORTS_INFO/>
  <REGISTERED_NAME>Webclient</REGISTERED_NAME>
  <REGISTERED_PASSWORD></REGISTERED_PASSWORD>
 </TAGLIST>
</CAS>  

Very little code is required to send a properly formed taglist to NET SatisFAXtion using Microsoft's XML and XMLHTTP APIs.  The following JavaScript example is a complete CAS XML processor (simplified for brevity) that loads a taglist from a file, sends the taglist to NET SatisFAXtion, and then saves the response taglist to a file.  In the example below, the function taglist in the input.xml file could contain everything necessary to send a fax including a cover page and attachments.

var XML	    = new ActiveXObject("Microsoft.XMLDOM");
var XMLHTTP = new ActiveXObject("Microsoft.XMLHTTP");

if (XML.load("input.xml"))
  {
  XMLHTTP.open("POST",
               "http://casdev.faxback.com/cgi-bin/casxml.asp",
               false);

  XMLHTTP.send(XML);

  XMLHTTP.ResponseXML.save("output.xml");
  }
else
  {
  alert(XML.parseError.reason+"\r"+XML.parseError.srcText);
  }

As an alternative to loading pre-made XML taglists into an XMLDOM object (from a file or a text string), you can create XML taglists dynamically by using the CAS XML Script Library.  For the most part, the functions in the script library are wrappers around the XML and XMLHTTP APIs, but as they are oriented around creating taglists they are generally easier to use than going directly to the XMLDOM. 

Taglists are constructed by creating an empty taglist with the xmlTlNew function, and then adding tags to that list with the xmlTlAddTag function.  The only case when tag order is important involves the first tag in a taglist, which is typically a function tag. Tags are added to a taglist sequentially; there is no capability to insert a tag at a specific location.

Tl = xmlTlNew();
xmlTlAddTag(Tl,"SEND_MESSAGE",null);
xmlTlAddTag(Tl,"REGISTERED_NAME","User1");
xmlTlAddTag(Tl,"REGISTERED_PASSWORD","");
xmlTlAddTag(Tl,"TRANSFER_TYPE",0);

Sections are created by calling the xmlTlCreateSection function.  Tags are then added to the new section with the same xmlTlAddTag function. The section is closed by calling the xmlTlCloseSection function. Once a section is closed, no more tags can be added to it, but more tags and sections can be added to the root of the taglist.

xmlTlCreateSection(Tl,"RECEIVER_ADDRESS","555-123-4567");
xmlTlAddTag(Tl,"RECEIVER_NAME","MyRecipient");
xmlTlCloseSection(Tl);

Taglists are sent to NET SatisFAXtion by calling the xmlTlSend function.  The xmlTlSend function uses HTTP to post the XML to a CAS/XML proxy according to a supplied URL.  The return value from xmlTlSend is an XMLDOM object containing the response XML from NET SatisFAXtion or from the script library itself, in the case of a communications error.

responseXML = xmlTlSend(Tl,
                        "\\\\CASDEV\\NETSATISFAXTION",
                        "NETSATISFAXTION",
                        2,
                        "http://casdev.faxback.com/cgi-bin/casxml.asp");

To work with response taglists from the fax server, the xmlTlGetTag function is used to search for tags and retrieve tag data in the response XML.  This function does little more than call the XMLDOM selectSingleNode method to locate a tag (element) within the XML and then return the text from that tag.  Tags at the root level of a taglist are retrieved by passing a tag name to the xmlTlGetTag function, for example:

stat = xmlTlGetTag(responseXML,"STATUS_NUM")

Tags located in sections within the taglist are retrieved by passing the xmlTlGetTag function an XPath that combines the section name and the tag name, for example, to read the connection seconds from the first MESSAGE_HANDLE section in a taglist the following XPath would be used:

secs = xmlTlGetTag(responseXML,"MESSAGE_HANDLE[0]/CONNECTION_SECONDS")

All standard XPath rules apply, and you are encouraged to use any of the functions available in the XMLDOM to search and retrieve information from the response XML.

The CAS/XML proxy relies on the host web server's HTTP (or HTTPS) communications services to perform most of the work of interacting with the client. The URL of the proxy is what links the client to NET SatisFAXtion.  Given the proxy URL, a client can access multiple NET SatisFAXtion servers through a single CAS/XML proxy.

Starting with version 7.0, NET SatisFAXtion includes an integrated HTTP server that has a built-in CAS/XML proxy.  The URL of the proxy, when sending CAS requests over a local LAN, is typically http://{server name}/casxml.api.  Alternatively, a CAS/XML proxy can be installed on Microsoft's IIS web server, by downloading the CAS XML Tools from this website.

The following diagrams illustrate the different types of connections that CAS XML clients can make:

Client Runs on Server            - or -  Client Connects to Server Over Local Area Network  Client <-- HTTP/HTTPS --> CAS/XML Proxy <-- IP/Memory --> Fax Server

Client Connects to Server Over Internet Client <-- HTTP/HTTPS --> CAS/XML Proxy <-- IP/Memory --> Fax Server Outside Firewall Inside Firewall

To execute a CAS function, clients use HTTP to "post" an XML taglist to a CAS/XML proxy, and then process the reply taglist either synchronously or asynchronously.  This differs from the CAS ActiveX interface, where the client is required to logon to a NET SatisFAXtion connection router as well as open and close network sessions while sending taglists.

The CAS XML client must provide the DOMAIN_NAME, REMOTE_LOGON_NAME and PROTOCOL that the proxy will use when connecting to NET SatisFAXtion.  For this reason, all CAS XML taglists must include a root <CAS> element, where the immediate child elements provide the proxy with the necessary logon information.  The taglist itself is contained within a <TAGLIST> element, which is also a child element immediately under the root <CAS> element.  For example:

<CAS>
 <DOMAIN_NAME>\\CASDEV\NETSATISFAXTION</DOMAIN_NAME>
 <REMOTE_LOGON_NAME>NETSATISFAXTION</REMOTE_LOGON_NAME>
 <PROTOCOL>2</PROTOCOL>
 <TAGLIST>
  <DELETE_MESSAGE/>
  <REGISTERED_NAME>Fred</REGISTERED_NAME>
  <REGISTERED_PASSWORD></REGISTERED_PASSWORD>
  <MESSAGE_HANDLE>10432</MESSAGE_HANDLE>
 </TAGLIST>
</CAS>  

The CAS XML Script Library provides functions that simplify XML taglist construction and automatically ensure that the XML is formatted properly.  It is, however, beneficial to understand the basic layout of XML taglists, for situations where taglists are created by other means, such as concatenating text strings.

Working with Files

When using CAS functions that work with files on the client computer (such as SEND_MESSAGE) or return files as output (such as GET_FILE_FUNCTION), the file content is included within the XML taglist as the data for the CONTENT_DATA tag, with the file content encoded in base64 format. Base64 encoding converts an arbitrary sequence of bytes into a text string consisting of US-ASCII characters that can be safely included in XML (see RFC 1521). The data for the CONTENT_DATA tag must always be encoded in base64.  For example, the following taglist sends a fax, with the cover text provided in the CONTENT_DATA tag:

<CAS>
 <DOMAIN_NAME>\\CASDEV\NETSATISFAXTION</DOMAIN_NAME>
 <REMOTE_LOGON_NAME>NETSATISFAXTION</REMOTE_LOGON_NAME>
 <PROTOCOL>2</PROTOCOL>
 <TAGLIST>
  <SEND_MESSAGE/>
  <REGISTERED_NAME>WEBCLIENT</REGISTERED_NAME>
  <REGISTERED_PASSWORD></REGISTERED_PASSWORD>
  <TRANSFER_TYPE>0</TRANSFER_TYPE>
  <BEGIN_SECTION>
   <RECEIVER_ADDRESS>555 123 1234</RECEIVER_ADDRESS>
   <RECEIVER_NAME>Test Recipient</RECEIVER_NAME>
  </BEGIN_SECTION>
  <BEGIN_SECTION>
   <CONTENT_PART>2</CONTENT_PART>
   <CONTENT_TYPE>1</CONTENT_TYPE>
   <CONTENT_DATA>VGV4dCB0byBhcHBlYXIgb24gdGhlIGNvdmVyIHBhZ2Uu</CONTENT_DATA>
  </BEGIN_SECTION>
 </TAGLIST>
</CAS>

Unlike the CAS ActiveX interface, where the CURRENT_FILESPEC and DESTINATION_FILESPEC tags are used to reference local files, with the CAS XML interface the CONTENT_DATA tag is used instead to contain the file within the XML.  For example, when retrieving an inbound fax from the server with GET_FILE_FUNCTION, the content of the file is included in the response XML. The application must extract the file content from the CONTENT_DATA tag, which is encoded in base64.  The following taglist is a response from NET SatisFAXtion after using GET_FILE_FUNCTION to retrieve a message attachment:

<CAS>
 <TAGLIST>
  <GET_FILE_RESULT/>
  <STATUS_NUM>0</STATUS_NUM>
  <STATUS>Operation Succeeded</STATUS>
  <CONTENT_DATA>VGV4dCB0byBhcHBlYXIgb24gdGhlIGNvdmVyIHBhZ2Uu</CONTENT_DATA>
 </TAGLIST>
 <STATUS_NUM>0</STATUS_NUM>
 <STATUS_EXTENDED_NUM>0</STATUS_EXTENDED_NUM>
 <STATUS/>
</CAS>

The FaxBackX ActiveX control, which is included with the CAS ActiveX controls, includes base64 conversion support, including methods that convert directly to and from files. Because of this and other features, the FaxBackX control is recommended whenever it is possible to install ActiveX controls on the client computer. As an alternative, the CAS XML Script Library provides script functions to perform base64 conversions without using the FaxBackX control.  However, the script library functions require the application to handle all file I/O if the source or destination data for the conversion resides in a file.

var FBX = new ActiveXObject("FaxBackX.soap");

function SendFaxFile( File )
  {
  var Tl = xmlTlNew();
  xmlTlAddTag(Tl,"SEND_MESSAGE",null);
  xmlTlAddTag(Tl,"REGISTERED_NAME","User1");
  xmlTlAddTag(Tl,"REGISTERED_PASSWORD","");
  xmlTlAddTag(Tl,"TRANSFER_TYPE",0);   // 1= EMAIL, 0=FAX

  xmlTlCreateSection(Tl,"RECEIVER_ADDRESS","555-123-4567");
    xmlTlAddTag(Tl,"RECEIVER_NAME","MyRecipient");
  xmlTlCloseSection(Tl);
    
  xmlTlCreateSection(Tl,"CONTENT_PART",3);  // Attachment
    xmlTlAddTag(Tl,"CONTENT_TYPE",0);
    xmlTlAddTag(Tl,"CONTENT_DATA",FBX.base64_encode_from_file(File));
  xmlTlCloseSection(Tl);
      
  var responseXML = xmlTlSend(Tl,
                              "\\\\FAX\\NETSAT",
                              "NETSAT",
                              2,
                              "http://netsat/casxml.asp");
    
  return(xmlTlGetTag(responseXML,"STATUS_NUM"));
  }

var FBX = new ActiveXObject("FaxBackX.soap");

function GetMessageFile( MsgHandle, MsgFileName, DestinationFile )
  {
  var Tl = xmlTlNew();
  xmlTlAddTag(Tl,"GET_FILE_FUNCTION",null);
  xmlTlAddTag(Tl,"REGISTERED_NAME",UserName);
  xmlTlAddTag(Tl,"REGISTERED_PASSWORD",UserPassword);
  xmlTlAddTag(Tl,"MESSAGE_HANDLE",MsgHandle);
  xmlTlAddTag(Tl,"CURRENT_FILESPEC",MsgFileName);

  var responseXML = xmlTlSend(Tl,
                              "\\\\FAX\\NETSAT",
                              "NETSAT",
                              2,
                              "http://netsat/casxml.asp");

  if (xmlTlGetTag(responseXML,"STATUS_NUM") == 0)
    {
      // Extract file from XML and convert from base64

    var FileContent = xmlTlGetTag(responseXML,"CONTENT_DATA");   

    FBX.base64_decode_to_file(FileContent,DestinationFile);
    }
  }

The script library can be used from script in ASP pages running on IIS, HTML files loaded by Internet Explorer, and stand-alone script files.  For example, the following line, referencing the VBScript version of the script library, can be added to an ASP page to access the script library functions:

<script language="VBScript" runat=server src="CASXMLLib.vbs"></script>

Select a link below for a detailed description of a CAS XML Script Library function.

To use FaxBackX, an application must first create a reference (or pointer) to the FaxBackX interface, and then save that reference so that it can be used globally throughout the application.  Although a single, global FaxBackX reference should suffice, there is no harm in creating multiple references to the ActiveX interface within the same application.

The following examples demonstrate accessing the FaxBackX interface from VBScript, JavaScript, and C++.  Although each language has a unique method of creating the ActiveX interface, all languages use the interface similarly.

Function AccessFaxBackX()
  Dim FBX, encoded
  
  Set FBX = CreateObject("FaxBackX.soap")

  encoded = FBX.base64_encode("Encode this string")
End Function

function AccessFaxBackX()
  {
  var FBX, encoded;
  
  FBX = new ActiveXObject("FaxBackX.soap");
 
  encoded = FBX.base64_encode("Encode this string");
  }

#include <windows.h>
#import <faxbackx.dll>
using namespace FAXBACKXLib;

void AccessFaxBackX()
  {
  Isoap  *FBX; 
  CLSID  class_id;
  
  CoInitialize(NULL);
  
  if (CLSIDFromProgID(L"FaxBackX.soap",&class_id) == S_OK)
    {
    if (CoCreateInstance(class_id,
                         NULL,
                         CLSCTX_INPROC_SERVER,
                         IID_IUnknown, 
                         (void **)&FBX) == S_OK)
      {
      _bstr_t encoded = FBX->base64_encode("Encode this string");

      FBX->Release();
      } 
    }

  CoUninitialize();
  }

Select a link below for a detailed description of a FaxBackX method.