The SuperCom DUAL API

Q: ActiveX or ActiveX API: What is the difference ?
A: ActiveX refers to the SuperCom ActiveX control (OLE / COM control). ActiveX API refers to the API introduced with the SuperCom ActiveX control and is currently offered via the SuperCom ActiveX control and the SuperCom .NET Class Library (class TSCom).

Example

  SCom.PortOpen = True
  SCom.Output = "Hello"

Q: What is the SuperCom DUAL API ?
A: The SuperCom DUAL API consists of the DLL API and the ActiveX API.
ActiveX API: The ActiveX API consists of Properties, Methods and Events provided by one ActiveX control (OLE / COM Control) or the SuperCom .NET Class Library.
The ActiveX API was implemented above the SuperCom DLL API.
DLL API: The DLL API is the combination of one or more runtime files (.DLL) and the corresponding import library (.LIB, .BAS, .PAS, .TPU etc.). The import library is inserted into the applications project and compiled. This way the application gains access to the functions located inside the DLL. The DLL is an external shared library of functions that is loaded when needed. A DLL takes code out of the executable, makes it smaller, it loads faster and it can be shared by many executables the same time. Windows automatically loads the DLL when the application calls for it. The most part of the Windows operating system consist of DLLs (Windows API). DLL's are maybe the most useful feature ever added to Windows and is the abutment of the Windows modularity concept. Thus the SuperCom DLL API fits excellent into the Windows modularity concept and using it is very easy.

With DUAL API you can choose to use one API or even both API's as it fits best.

Q: What is the SuperCom DLL API ?
A: The DLL API is the combination of one or more runtime files (.DLL) and the corresponding import library (.LIB, .BAS, .PAS, .TPU etc.). The import library is inserted into the applications project and compiled. This way the application gains access to the functions located inside the DLL.

The DLL API is functional grouped into two categories: a) the Low Level functions operating close to the underlying hardware and each name starts with Com... (e.g. ComInit) and b) the High Level functions operating above the low level functions, not bound to a specific hardware and each name starts with RS... (e.g. RS_TXPInTime).

Example

  ComInit(COM_1)
  ComSetState(COM_1, 9600,,,)
  ComWriteEx(COM_1, "Hello", strlen("Hello"))

DLL: A DLL is an external shared library of functions that is loaded when needed. A DLL takes code out of the executable, makes it smaller, it loads faster and it can be shared by many executables the same time. Windows automatically loads the DLL when the application calls for it. The most part of the Windows operating system consist of DLLs (Windows API). DLL's are maybe the most useful feature ever added to Windows and is the abutment of the Windows modularity concept. Thus the SuperCom DLL API fits excellent into the Windows modularity concept and using it is very easy.

Q: What is the SuperCom ActiveX API ?
A: The ActiveX API consists of Properties and Methods provided by one ActiveX control or the SuperCom .NET Class Library. The ActiveX API is available automatically after installation within the development environment e.g. Visual Basic, VBA, Visual C++, C++ Builder, C#, VB .net, Delphi etc.

Q: Do I have to choose an API in advance ?
A: Users of a SuperCom DUAL API software package are in position to select the most suitable API or they can use the ActiveX properties and methods and also call DLL functions. By combining both APIs a very big function set is available to the application. It opens unforeseen potentialities. For instance while the application administrates the data link using the high level ActiveX properties it can call DLL functions to perform low level tasks. Using low level DLL functions it's even possible to enhance or change the behavior of the event reporting mechanism within the ActiveX. The DLL API also includes intelligent high level functions which may run faster or offer more possibilities that the corresponding ActiveX property or method.

Q: What to use in a NET development environment ?
A: Using SuperCom in Microsoft .NET Framework (e.g. C#, VB Net) offers nothing less than the known DLL API and Activex API. Both API are compatible to the well known but the new class library offers a lot more. Developers can now use the DLL API and the ActiveX API via the SuperCom .NET Class Library and even combine both API as needed since the class library includes both. Thus the SuperCom ActiveX is not needed in order to use the ActiveX API. Naturally, the SuperCom ActiveX control can still be used within .NET, if required.

The SuperCom .NET Class Library is included in every DLL API and DUAL API SuperCom completely with its C# source code and can be used with NET aware compilers like C#, VB Net and C++. The SuperCom .NET Class Library is available in 32 bit and 64 bit SuperCom packages.

.NET code snippets      FAQ      List of available NET sample programs

        using ADONTEC.Comm;  // see C# source in SComClass.cs
           :                 // VB Net references the class DLL
           :
        public class MYSCOM : TSCom
        {
            public MYSCOM(int CommId, Form frm)
                : base(CommId, frm) // pass the window handle to TSCom
            {

            }
            protected override void OnComm(OnCommEventArgs e)
            {
                int SComEvent = (int)e.EventCode;

                if (SuperCom.BitsSet(SComEvent, SuperCom.EV_RXCHAR))

                if (SuperCom.BitsSet(SComEvent, SuperCom.EV_TXEMPTY))

                if (SuperCom.BitsSet(SComEvent, SuperCom.EV_TRIGGER))

                if (SuperCom.BitsSet(SComEvent, SuperCom.EV_RING))
                   :
                   :
                e.RetCode = 0;
            }
            protected override void OnConnect(OnConnectEventArgs e)
            {
                switch (e.Action) // handle event
                {
                    case SuperCom.acCONNECT_INFO:
                    case SuperCom.acCONNECT_DIALING:
                    case SuperCom.acCONNECT_OK:
                       :
                       :
                }
            }
            protected override void OnFile(OnFileEventArgs e)
            {
                switch (e.Action)
                {
                    case SuperCom.acFILENAME:
                    case SuperCom.acFILEDATA:
                    case SuperCom.acSYN:
                    case SuperCom.acRXING:
                    case SuperCom.acTXING:
                    case SuperCom.acRXFIN:
                    case SuperCom.acTXFIN:
                        :
                }
            }
            protected override void OnDataPacket(OnDataPacketEventArgs e)
            {
                switch (e.Action)
                {
                    case OnDataPacketEventCode.SCOMM_DATAPACKET_OK:
                    case OnDataPacketEventCode.SCOMM_DATAPACKET_NOK:
                    :
                }
            }

        } //MYSCOM

        SCom = new MYSCOM(Com, frm1);

         // Set some comm parameters
        SCom.ComType = ComType.COMTYPE_RS232; // *) serial, TAPI, TCP/IP, ISDN
        SCom.Settings = "115200,N,8,1";
                // or
        SCom.BaudRate = 115200;
        SCom.DataBits = 8;
        SCom.StopBits = StopBits.One;
        SCom.Parity = Parity.None;

        SCom.Handshaking = Handshaking.SCOMM_HANDSHAKE_CTS;

        SCom.PortOpen = true;  // Ready to take action...
         :
             // need some trigger to report when received ?
        SCom.Trigger = SuperCom.StringToByteArray("Username");
        SCom.TriggerAction = TriggerAction.SCOMM_TRIGGER_ADD;
        SCom.Trigger = SuperCom.StringToByteArray("Password");
        SCom.TriggerAction = TriggerAction.SCOMM_TRIGGER_ADD;

              // now connect to a modem server ..
        SCom.ConnectAddress="1234 5678 99"; // phone number
        SCom.Connect = true;
         :
              // transmit a file
        SCom.FileName = "sales.doc";
        SCom.Protocol = Protocol.PROTOCOL_ZMODEM;
        SCom.FileTransmit = true;
         :
  

In the above sample we've done serial communications. Now we need to send files
to a TCP/IP server. We can create a new class or reuse the one we had in
the previous sample for serial communications.
         :
        SCom.PortOpen = false; // close that one...
        SCom.CommPort = ClientCom;  // switch comm index, if needed...
        SCom.ComType = ComType.COMTYPE_WINSOCK_CLIENT; // *) serial, TAPI, TCP/IP, ISDN
        SCom.PortOpen = true; // Ready to take actions ...
         :
              // now connect to a TCP/IP server ..
        SCom.ConnectAddress="www.weburl.com:9000";
        SCom.Connect = true;
         :
              // transmit a file
        SCom.FileName = "sales.doc";
        SCom.Protocol = Protocol.PROTOCOL_ZMODEM;
        SCom.FileTransmit = true;
         :
  

Q: Can I use SuperCom functions and protocols in combination with a third-party communication toolkit ?
A: SuperCom provides functions to integrate or share connections and/or links established by a third-party toolkit. For instance an application uses a third party TCP/IP component to connect to a server but need to use the SuperCom ZMODEM protocol. Several samples available.
NOTE: Since not all configurations are possible and not all third party components are providing the expected functionality, we suggest you to contact our technical support and discuss the matter.

Q: Do I have any influence on the reported events ?
A: Yes, both API (ActiveX API and the DLL API) offer properties and functions to suppress unwanted events.

Q: Is it possible to monitor an adjust events on low level ?
A: A rather rare application but it is possible. The DLL API can install a user function within the event reporting chain in order to monitor, filter, adjust events on the way to the application.
See the following C/C++ sample.

Event function filtering communications events: Sample

// The following event function will filter the modem event "RING"
// thus it will not get reported to the application.

   PUSEREVENTPROC pXEventProc = NULL;  // previous/original event handler

   DWORD COMMAPI EventFilterProc (TCOMMID CommId, DWORD SComEvent)
   {
      DWORD Res=0;

      if (SComEvent & EV_RI)
      {
           // Clear bits that we don't want to get reported
           // All other events, while enabled, will reach the application
         SComEvent = ~EV_RI;  // clear
         SComEvent |= EV_DCD; // set
      }

          // If anything to report, call the previous/original event handler
      if ( (SComEvent != 0) && (pXEventProc != NULL) )
         Res = ComCallUserEventProc (pXEventProc, CommId, SComEvent); 

      return (Res);
   }

 //  Setup:
 //   First we setup the new event handler and store the address of the
 //   previous/original event handler so we can call it when needed

   pXEventProc = ComGetSetEventProc(CommId, EventFilterProc);
     :
     :