General
CapeSoft Logo

CapeSoft NetTalk

Download Latest Version
Installed Version Latest Version
Upgrading to NT12 Web Server Web Client Email FTP

Learning NetTalk


I'm New to NetTalk

NetTalk is the de-facto standard tool for TCP/IP networking in Clarion. From using it extensively ourselves, we know why. There simply is no easier way to add robust networking to your Clarion application. Built by people who use Clarion, for people who use Clarion, it's no wonder that NetTalk offers a level of integration not found in other tools.

This section is here to provide you with information that will help you learn about NetTalk as quickly as possible:

Some tips that will help you use the NetTalk documentation:
Where to now?

NetTalk is a hugely powerful Clarion Toolkit, which allows you to add networking functionality to your application.

Following that we suggest you familiarize yourself with the following sections:

Introduction This section will help you find out what NetTalk offers and it describes the difference between the NetAuto and NetSimple classes.
Class Overview A key place for quickly finding help on the different NetAuto and NetSimple objects.
Definition of NetAuto "Server" and "Client" A good concept definition that is essential for you to grasp before you tackle network applications.
Using NetTalk in your application A very good guide as to which classes you should use.
Examples We've also packaged an excellent selection of examples with NetTalk. You may often want to read the documentation in conjunction with these examples, that are found in your Clarion/3rdParty/Examples/NetTalk folder.
Debug and Logging Section
Error Messages
FAQ
This section will help you debug your code. We've also added an error messages and a FAQ (Frequently Asked Questions) section.
Support If you need support please check this section first to guide you through the getting support procedure.

Go ahead, and enjoy adding networking to your applications.

Introduction

More and more users are discovering that NetTalk is the premier TCP/IP solution for Clarion programmers. This isn't too surprising given the amazing power, coupled with ease of use, that NetTalk provides. Here's a brief outline of some of functionality available to you:

1. NetAuto Classes (Desktop Level)

The NetAuto objects support the NetAuto protocol. These objects provide you with the following functionality:

2. NetSimple Classes (Desktop Level)

The NetSimple classes support normal Winsock and socket communication. Communications can be in plain text, or secured with TLS. These classes provide you with the following functionality:

3. Web Server Classes and Templates  (Server and Apps level)

The Web Server classes allow you to create rich, interactive, web applications in Clarion.  The Web server templates are a very mature, feature rich, template set which allow you to leverage your existing Clarion skills to create state-of-the-art web applications. A key aspect of these applications is the ease of deployment, and their ability to scale up to service large number of users.

They also make it trivial to create, and deploy, Web Service API's - allowing other systems to interact with your database, and program functionality, using industry standards like SOAP and REST.

4. NetDUN Classes (Dial-Up Networking)

The NetDUN class allows you to add Dial-Up functionality into your application.
At heart, NetTalk builds TCP/IP communication between two or more computers (or processes) into your application. These processes don't have to be on the same machine in order to perform the communication. NetTalk provides you with easy-to-use functionality for adding network communication to your application.

Examples

NetTalk comes packed with lots of examples. Here are some selected ones you should consider using;
Example Location Primary Use
NetDemo.App \Clarion\Examples\NetTalk\Demo The primary demo for NetTalk Desktop functionality. This demo is often used for testing connectivity, or the settings for any specific feature. It's is a go-to demo, especially when debugging. 
demo.app Clarion10\Examples\NetTalk\Email\Demo
Clarion10\Examples\NetTalk\Email\DemoLegacy
A definitive demo for email functionality. Contains procedures, and table structures, you can import directly into your application.
ftpdemo.app
ftpLegacy.app
Clarion10\Examples\NetTalk\FTP\ABC
Clarion10\Examples\NetTalk\FTP\Legacy
Definitive demos for FTP functionality. Contains procedures that can be imported directly into your application.

Class Overview

 

Copyright, License and Distribution

Copyright and License

This product is copyright 2000-2024 by CapeSoft Software.

NetTalk and associated DLL files may be distributed royalty free with your applications.
CARoot.PEM and DH2048.PEM files can be distributed royalty free with your applications.

You are not allowed to copy any Template (TPL) files, Library (LIB) files, Source (CLW, INC) and documentation files.

Each developer needs his own license to use NetTalk. (Need to buy more licenses?)

This product is provided as-is. CapeSoft Software and CapeSoft Electronics (collectively trading as CapeSoft), their employees and dealers explicitly accept no liability for any loss or damages which may occur from using this package. Use of this package constitutes agreement with this license. This package is used entirely at your own risk.

Use of this product implies your acceptance of this, along with the recognition of the copyright stated above. In no way will CapeSoft , their employees or affiliates be liable in any way for any damages or business losses you may incur as a direct or indirect result of using this product.

Distribution

This product, and all the files contained therein (except where specifically noted otherwise), are copyrighted by CapeSoft Software who trade as CapeSoft. You will, however, need to copy the following files and distribute them with your applications if you compile your application in Standalone (ie DLL) mode:

CLANET.DLL, CLARUN.DLL, CLADOS.DLL

NetTalk uses the DOS driver (which is automatically added to your project by the NetTalk template).

Transport Layer Security (TLS)

This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit. This code is Copyright (c) 1998-2019 The OpenSSL Project. All rights reserved. It is included here under the terms of their license.

If you use any of the TLS features in NetTalk, then you will need to distribute additional files. See here for more information.

Web Server applications

You are permitted to ship all the runtime files required by the web server  located in the \Clarion\accessory\Libsrc\win\NetWeb folder.

To support GZIP functionality in the server make sure you deploy the ZLIBWAPI.DLL file as well.

It's best to deploy all DLLs required into the same folder as the Exe.


Deploying a TLS Client or Server

The target machine needs to have the Visual Studio 2017 (x86) runtime installed.

Deploying a secure server or client is really no different from deploying a normal program. However some additional files are probably necessary. As of the time of writing the files are;

All these files can all be found in your application directory - they are moved there automatically by the IDE. If you have disabled this IDE function then you'll find them in the \clarion\accessory\bin folder. These shipping files are updated from time to time, but you can update the files yourself at any time.

If you fail to install the redistributable files then you will likely see a runtime error VCRuntime140.DLL missing.

ZlibWapi.DLL

This file is needed for all servers, secure ones and insecure ones.

ECEC.DLL

This file is needed by Apps Servers that have implemented Push Notifications

OpenSSL.Exe

This program is only needed if you are deploying a WebServer which will make use of LetsEncrypt.org to get certificates.

caroot.pem

If you are deploying an TLS Client (such as Email, FTP or Web client) then you will need to ship the caroot.pem file. This is the list of root certificates that are "trusted" by the client. The file shipped with NetTalk is based on the CA certificates supported by Mozilla (Firefox). They can be downloaded from
https://curl.haxx.se/docs/caextract.html

An alternative root file, maintained by Google, can be downloaded from https://pki.goog/roots.pem.

dh2048.pem

The dh2048.pem file is a set of DH initialization parameters used to support the DH cipher in OpenSSL in a server. You only need to distribute this file if you are making a TLS Server of some kind.

 You can replace the dh2048.pem with your own set of parameters if you wish. To generate your own file
  1. Open a Command Prompt window
  2. Go to the \clarion\accessory\bin folder
  3. Execute
    openssl dhparam -out dh2048.pem 2048
  4. Move the resultant dh2048.pem file to the \clarion\accessory\libsrc\win folder.

Acknowledgements

Some of the the DLL files are from OpenSSL and are included under the terms of their license.

ZLIB is the product of Jean-loup Gailly and Mark Adler and is distributed under the terms of their license at www.zlib.net/zlib_license.html.


TroubleShooting

If you've done all the above, and you still get an error connecting to a TLS server, then try running OpenSSL.Exe manually to see if it gives an error. If you get this error;

The program can't start because api-ms-win-crt-runtime-l1-1-0.dll is missing from your computer.

The missing dll api-ms-win-crt-runtime-l1-1-0.dll is installed with a Windows update. To resolve this issue, download and install the Update for Universal C Runtime in Windows from Microsoft. Note that this update in turn requires that the OS be reasonably up to date. (For example Windows 7 must be on at least Service Pack 1, and so on.)

If you get this error running your web server, then you have not deployed the latest CLANET.DLL to match your NetTalk version.

OPENSSL_Uplink : no OPENSSL_Applink

 

Acknowledgements

NetTalk is enhanced by the inclusion of code from several different sources. Our thanks and appreciation go to all the following programmers and projects.

Dries Driessen has contributed code to various parts of NetTalk and his work is included here under license. He was also instrumental in the creation of jFiles which is an integral part of much of the API functionality.

Many thanks to Geoff Robinson for ongoing feedback and contributions to StringTheory, including bug fixes, improvements and new methods.

Donald Ridley has contributed significant code to the mBuild utility.

Mark Sarson contributed the Clarion Syntax for the ACE Code editor. Those files are included here with his permission (and his MIT License).

NetTalk includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit. This code is Copyright (c) 1998-2019 by The OpenSSL Project. All rights reserved. It is included here under the terms of their license.
OpenSSL includes cryptographic software written by Eric Young of Cryptsoft.

This product includes code developed by the jQuery Project and is included here under the terms of the MIT license.

The jQuery Media and jQuery Form plugins are Copyright by M. Alsup and is included here under the terms of the MIT license.
The jCanvas plugin is Copyright by Caleb Evans and is included here under the terms of the MIT license.
The Ad-Gallery plugin is Copyright by Anders Ekdahl and is included here under the terms of the MIT license.
The jQuery File Upload plugin is Copyright by Sebastian Tschan and is included here under the terms of the MIT license.
The Signature Pad plugin is Copyright by Thomas J Bradley and is included here under the terms of the New BSD license.
The FlashCanvas code is Copyright by Tim Cameron Ryan and the FlashCanvar Project. It is included here under the terms of the MIT license.
The json2.js file is written and maintained by Douglas Crockford and is in the public domain.
The QuaggaJs plugin is Copyright by Christoph Oberhofer and is included here under the terms of the MIT License.
The jsQR plugin is Copyright by Cosmo Wolfe and is included here under the terms of the Apache License 2.0

The TinyMCE HTML Editor is copyright by Moxiecode Systems and is included under the terms of the LGPL license.
The Redactor HTML editor is copyright by Imperavi Inc and is included under the terms of their OEM license.
the CKEditor4 HTML Editor is copyright by CKSource Frederico Knabben and is distributed under the terms of the  LGPL.
The Advanced Code Editor (ACE) is copyright by Ajax.Org and is included under the terms of the MPL license.


NetTalk allows developers with a CloudMade API Key to make use of this service.

Installation Instructions

To install NetTalk run the supplied installation program.
Download the latest version of NetTalk from: capesoft.com/accessories/downloads.htm#nettalk.

Definitions: "Client" and "Server"

Definition: A Client is the process that initiates the conversation.

Definition: A Server cannot initiate a conversation - it only responds to incoming requests.

A process that requests information is called a client, while the process that receives a request and then provides a reply to that request is a server. Thus a TimeClient is the process that will request the time from the TimeServer, which supplies the TimeClient with the correct time.

In some cases a process (such as a Chat program) will be both the client and the server. It can both initiate conversation and respond to conversation. It initiates conversation when the user clicks the button to send the Chat string, and it responds when someone else sends it a Chat string. 

In fact a client is also always a server (in that it listens to replies), whereas a server is not a client because it does not initiate communication. If we use an analogy of the telephone, we find that a telephone is both a client and a server. The telephone can dial (initiate communication), but it can also receive calls (server mode). Whereas an answering machine is only ever a server (it never initiates communication), it only records a conversation initiated by someone else.

Using NetTalk in your Applications

The following section describes how to use NetTalk in your applications. NetTalk shields you from the complexities of network communication, so you will soon find that it is easy to implement NetTalk communication in your application. We've put together some ways that you can use NetTalk in your application
  1. I want to use the Control or Global Templates - This is a very quick and simple method to drop NetTalk functionality into your application. It only gives you the functionality of the pre-built Control Templates. Click here for the Control Templates section to learn how to do this.
    • Use_NetRefresh (Global Template) - uses NetAuto to add functionality so that data changes in one application get reflected immediately on the screens of all other applications using this data. (LAN Only)
    • ChatControl (Control Template)- adds a NetAuto Chat facility to your application (allowing you to send text Chat strings over the network). (LAN Only)
    • CloseAppControls (Control Template)- adds the remote application closing functionality (allowing someone like a system administrator to remotely close down all instances of your application) using NetAuto. (LAN Only)
    • UseRemoteMachineControls (Control Template)- adds the ability to use NetAuto over a WAN or the Internet by connecting you to remote machines. (LAN Only)
    • SendEmailControls (Control Template)- adds the basic controls for using sending email.
    • FTPControls (a set of 2 extension and control templates, as well as a utility to import the FTPFiles procedures) - adds the basic FTP functionality to your program.
  2. You can use some of the other pre-built NetAuto classes for LAN Only environments -
    These include the:
    • Time Client/Server
    • File Client/Server
    • Close Application Client/Server
    • Chat Client & Server.
    These classes will allow you to quickly add file transfer, time synchronization, remote application closing or chat functionality to your application. These classes are described in the Using the Other NetAuto classes section. The Chat and Remote Application closing classes are provided as Control templates.
  3. You can use some of the other pre-built NetSimple classes for accessing Internet Protocols -
    These include the: These classes will allow you to quickly add their respective capabilities to your application.
  4. I want my application to be able to communicate over a LAN  network to other applications I write - Gain the full power of NetAuto. NetAuto allows you to make instances of the powerful NetServer and NetClient classes. You can then derive your own functionality from them. This is the most powerful and flexible way of using NetAuto. To explain how to do this we have created three scenarios which will help you to see examples of how to generate your own network applications. Click here for the Programming - NetAuto Protocol and NetAuto classes section to learn how to do this.
  5. I want my application to be able to communicate over a LAN, WAN or Internet to other applications I write - While the NetAuto classes offers LAN capabilities the NetSimple classes offer you the ability to talk over a LAN, WAN or the Internet. These are very powerful and easy to use classes that allow you to communicate using standard TCP/IP or UDP. Read more about the NetSimple Classes.
  6. I want my application to talk to other network applications. You can talk directly to a port on a machine. This is handy when you want interface with another process that does not use the NetAuto protocol. For example you may want to access a Java, C or C# network application. In these cases you will use the NetSimple class.
  7. (Very Advanced Users Only): You can call the NetTalk DLL functions directly. 99% of the functionality of NetTalk has been coded into the NetTalk classes and control templates which create an easy way for you to use NetTalk. If you are a hard core programmer you may want to call some of the DLL functions directly. Some of these functions will allow you to set various options, or get network information. The DLL functions are described in more detail in the DLL functions section. You will probably also want to look at the code in the net*.clw and net*.inc files in your Clarion/LibSrc folder.
Remember:
We have also included a whole set of examples and the scenarios in the Clarion/3rdParty/Examples/NetTalk folder. For more details see the Examples.

You can also look at the source code for the NetTalk classes which are found in your Clarion/LibSrc folder. The NetTalk files (net*.clw and net*.inc) contain the code for all the NetTalk classes.

Class Index

[End of this document]
Return to NetTalk Documentation Index