Overview

The CAS API is a flexible interface to NET SatisFAXtion, with support for several programming languages.  With CAS you can send and copy faxes, process and route inbound faxes, and monitor fax activity on a NET SatisFAXtion fax server.  All CAS documentation is available on this website. Using the CAS Samples, it takes only seconds to send your first fax.  Source code is available with each sample, that you can copy and use immediately.

The CAS 2.0 (Communications Application Specification) API is available through ActiveX and XML interfaces, providing access to NET SatisFAXtion from ASP/ASPX pages, JavaScript/VBScript, Visual Basic, C++ and C# applications. Applications that use CAS can be written for Windows or other operating systems, and they can run on LAN or Internet clients, on web servers (ASP/ASPX) or directly on NET SatisFAXtion servers.

CAS Clients ASP / ASPX Script Host Win32 / .NET VBScript, JavaScript Visual Basic, C++, C# CAS ActiveX / XML Interface IP NetBIOS Memory HTTP NET SatisFAXtion

The CAS API defines function and data "tags" to structure client-server exchanges between CAS clients and a NET SatisFAXtion server.  A CAS tag is essentially a blob of data, identified by a meaningful name. For example, to send a fax, a CAS client would construct a function request using the SEND_MESSAGE tag and the reply would include a MESSAGE_HANDLE tag that contained the handle for the new fax message.

Tags can be combined to form "taglists". Taglists typically start with a function tag, followed by one or more data tags (the parameters for the function). Tags containing various data types can be placed in the same taglist.  Taglists can also contain nested taglists, called "sections", that allow information such as fax numbers and attachments to be included multiple times within the same taglist. For example, the following SEND_MESSAGE taglist sends a fax message to 555-1234:

Tag Name	Tag Data
SEND_MESSAGE
REGISTERED_NAME	Fred
REGISTERED_PASSWORD
TRANSFER_TYPE	0
SUBJECT	This is the subject
BEGIN_SECTION
RECEIVER_ADDRESS	555-1234
RECEIVER_NAME	Wilma
END_SECTION
BEGIN_SECTION
CONTENT_PART	2
CONTENT_TYPE	1
CONTENT_DATA	This is my cover text!
END_SECTION

The CAS Tags section of this website lists several function tags that allow you to:

• Send fax and e-mail messages (SEND_MESSAGE) 
• Reschedule messages in the fax server send queue (MODIFY_MESSAGE)
• Examine the contents of fax server queues (GET_Q_ENTRIES_INFO)
• Retrieve inbound faxes from the fax server (GET_FILE_FUNCTION)
• Forward (route) messages to fax server users (COPY_MESSAGE)
• Delete faxes from any fax server queue (DELETE_MESSAGE)
• Get fax port status and configuration settings (GET_PORTS_INFO) 

All function taglists are created similarly to the SEND_MESSAGE example above.  The first two parameters are the REGISTERED_NAME and REGISTERED_PASSWORD that identify the fax server user or supervisor who is calling the function.  Fax server users can only retrieve, modify and delete messages that they submitted or messages for which they assumed ownership either through automatic routing or manual forwarding.  No restrictions are imposed on fax server supervisors. 

NET SatisFAXtion returns a taglist to the client in response to processing a CAS function.  Response taglists include STATUS_NUM and STATUS tags that tell whether the function was successful, as well as other tags that are specific to the function that was called.  For example, the following is a response taglist from calling the SEND_MESSAGE function.  The returned MESSAGE_HANDLE can be used by an application in subsequent function taglists to track the progress of the message that was submitted to the fax server.

Tag Name	Tag Data
SEND_MESSAGE_RESULT
MESSAGE_HANDLE	434
STATUS	Ok
STATUS_NUM	0
OS_SPECIFIC_ERROR	0

CAS Interfaces

You have a choice of two interfaces when writing a CAS application: ActiveX or XML.  Taglists are constructed, exchanged with NET SatisFAXtion, and parsed differently depending on the CAS interface that is used.  However, the order and meaning of CAS tags in taglists is nearly identical for both interfaces.  Thus, source code that demonstrates a CAS taglist formed using the ActiveX interface also demonstrates how the taglist should be formed using the XML interface.

The CAS ActiveX interface provides methods for creating and managing taglists, and communications drivers for sending and receiving taglists to/from NET SatisFAXtion.  CAS ActiveX controls must be installed on the client computer to use this interface.  The ActiveX interface provides the necessary functionality to interact with NET SatisFAXtion over LAN and Internet protocols, as well as direct-memory.

• CAS ActiveX methods create taglists, send taglists to the CAS driver to be processed locally by the CAS driver or remotely by a NET SatisFAXtion server, and retrieve and analyze response taglists.  For example, CAS ActiveX methods are highlighted in the snippet of JavaScript code that follows:

  SendTaglist = CAS.New();
  CAS.AddTag(SendTaglist,"DELETE_MESSAGE","");
  CAS.AddTag(SendTaglist,"REGISTERED_NAME",UserName);
  CAS.AddTag(SendTaglist,"REGISTERED_PASSWORD",UserPassword);
  CAS.AddTag(SendTaglist,"MESSAGE_HANDLE",MessageHandle);
  ResponseTaglist = CAS.Send(Instance,SendTaglist);
  LastErrorNum = CAS.GetTag(ResponseTaglist,"STATUS_NUM",0);
  LastErrorStr = CAS.GetTag(ResponseTaglist,"STATUS",0);
  CAS.Delete(ResponseTaglist);

• CAS tags describe the type of elements contained within a taglist.  For example, CAS tags are now highlighted in the snippet of JavaScript code that follows:

  SendTaglist = CAS.New();
  CAS.AddTag(SendTaglist,"DELETE_MESSAGE","");
  CAS.AddTag(SendTaglist,"REGISTERED_NAME",UserName);
  CAS.AddTag(SendTaglist,"REGISTERED_PASSWORD",UserPassword);
  CAS.AddTag(SendTaglist,"MESSAGE_HANDLE",MessageHandle);
  ResponseTaglist = CAS.Send(Instance,SendTaglist);
  LastErrorNum = CAS.GetTag(ResponseTaglist,"STATUS_NUM",0);
  LastErrorStr = CAS.GetTag(ResponseTaglist,"STATUS",0);
  CAS.Delete(ResponseTaglist);

The CAS XML interface relies on the standardized formatting of XML, and HTTP communications services that are readily available in many development platforms.  With the XML interface, an application creates an XML function request, sends/receives XML with NET SatisFAXtion via HTTP, and parses the XML response.  This can be achieved without installing CAS ActiveX controls on the client computer, allowing CAS applications to be written for a variety of operating systems.

• FaxBack created the CAS XML Script Library, utilizing Microsoft XML and XMLHTTP APIs to simplify creating and exchanging CAS XML taglists with NET SatisFAXtion.  The library is available in JavaScript and VBScript versions.  The following VBScript example uses the library to create and send a CAS XML taglist:

  Set Tl = xmlTlNew()
  Call xmlTlAddTag(Tl,"DELETE_MESSAGE","")
  Call xmlTlAddTag(Tl,"REGISTERED_NAME",UserName)
  Call xmlTlAddTag(Tl,"REGISTERED_PASSWORD",UserPassword)
  Call xmlTlAddTag(Tl,"MESSAGE_HANDLE",MessageHandle)
  Set responseXML = xmlTlSend(Tl, _
                              "\\CASDEV\NETSATISFAXTION", _
                              "NETSATISFAXTION", _
                              2, _
                              CASDevProxyURL)
  LastErrorNum = xmlTlGetTag(responseXML,"STATUS_NUM")
  LastErrorStr = xmlTlGetTag(responseXML,"STATUS")

• CAS XML taglists can be formed in many ways, such as building the XML as a text string (see the CAS XML Interface for details).  The prepared XML can be loaded into an XML object and sent to NET SatisFAXtion.

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

The decision of which interface to use should be made based upon the type of application being written.  A script that will be loaded by the NET SatisFAXtion Script Engine should be written using the ActiveX interface, to take advantage of direct-memory communications with the fax server.  An application that communicates over the Internet, or one that must run on a computer where CAS ActiveX controls cannot be installed (such as a non-Windows system) should use the XML interface.

Getting Started

The best way to begin developing your first CAS application is to try out the CAS Samples available on this website.  In addition to providing working examples, the CAS Samples can work with your NET SatisFAXtion server, simply by changing the logon parameters.  You should then examine the CAS ActiveX Interface or CAS XML Interface pages, based on the interface you have chosen for development.