CapeSoft.Com
Clarion Accessories
NetTalk
Doc Index
Version History
CapeSoft Logo

CapeSoft NetTalk

Download Latest Version
Installed Version Latest Version
Upgrading to NT9 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

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

2. NetSimple Classes

The NetSimple classes support normal Winsock and socket communication. These classess provide you with the following functionality:

3. NetDUN Classes (Dial-Up Networking)

The NetDUN class allows you to add Dial-Up functionality into your application.

4. Web Server Classes and Templates

NetTalk includes a powerful framework for creating Web server applications directly in Clarion. This allows you to extend the reach of your data from the LAN to the WAN.
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.

Jump Starts

Jump Start header Keen to get started? Then Jump Start sections are just for you - the basics on how to get NetTalk into your application as quickly and simply as possible.
We've included a number of step-by-step jump start examples that will help you add NetTalk to your application in almost no time at all.
Jump Starts

NetSimple Classes

Sending Emails For sending emails.
Receiving Emails For receiving emails.
Web Clients For adding Web Client functionality (i.e. Download files or web pages) using HTTP or HTTPS (Secure HTTP).
FTP Clients For FTP Client functionality (get directories, put or get files)

Learning How to Use NetAuto

Scenario One Single packet NetAuto Client/Server
Scenario Two Broadcasting packets NetAuto Client/Server
Scenario Three Multiple packets NetAuto Client/Server

NetAuto Classes

Chat Controls For adding the Chat Controls to your application to create a simple text chat application.
Close App Controls For adding the Close App Controls to your application to allow your application to be shut down remotely.
DIP For adding the NetDIP (Dynamic IP Management) functionality into your application. This will let your application run in "server" mode even though the IP of your machine may change or may be unknown to your clients. Particularly useful for WAN or Dial-Up.
NetRefresh For adding the NetRefresh functionality to your application. NetRefresh allows your browses to automatically refresh when someone else (on another machine) updates data.
Use Remote Machine Controls For adding the UseRemote control template to your application. (More advanced).
Please remember that the you should still read through the documentation (specially the scenarios) if you want to get the maximum functionality of NetTalk into your applications.

Examples

NetTalk comes packed with examples. Here are a couple tips for getting your teeth into NetTalk:

NetTalk Demo Application
NetDemo Application

NetTalk Proxy example screenshot
Proxy Debugging Example Tool

 

Class Overview

NetTalk presents you with the following classes and templates:

Global Templates

Activate_NetTalk This Global Template must be added to your application to use any of the following features.
Use_NetRefresh Add this Global Template to use NetRefresh in your application.

Control Templates

ChatControls This control template quickly adds all the chat controls to your window.
CloseAppControls This control adds the controls for closing down your application remotely. 
SendEmailControls This adds basic controls for sending email. For more functionality you will need to use the NetSendEmail class directly.
UseRemoteMachine Adds the controls to connect to remote machine on a WAN or the Internet. Most people will probably rather use the NetDIP class to do this now.

NetAuto Classes

NetTalk Object Tree png

    NetServer
NetClient
The Main NetAuto classes. These provide you with the greatest degree of flexibility when using the incredibly robust NetAuto protocol.
NetAutoCloseServer
NetCloseApps

NetChat
NetGetFile
NetFileServer
NetGetTime
NetTimeServer

NetRefresh
Specific classes based on the NetAuto technology (NetServer & NetClient). Some of these classes can be included into your application using Control Templates or Extension Templates.
    NetSecurityServer
NetSecurityClient
These are unsupported at the moment, but will form joint functionality with CapeSoft's Secwin product to provide licensing control to applications.

NetSimple Classes

NetSimple Object Tree png
NetSimple This class allows you to establish client socket connections to another server, or to behave like a server and listen on a port for incoming connections.
NetSimpleMultiClient This class allows you to establish multiple clientsocket connections to another server.
NetEmailSend
NetEmailReceive
These classes allows you to send and receive email
NetNewsSend
NetNewsReceive
These classes allows you to send and receive news
NetDIP This class provides Dynamic IP Management to your application. This class allows you to connect to a DIP server, which will tell your application instance about all the other people running your application. 
NetFTPClient These two classes (NetFTPClientControl & NetFTPClientData) allow you to build FTP clients to connect to FTP servers and download and upload files.
NetWebClient This class allows you to connect to web servers and download pages as well as posting data to web page forms.

NetAuto Object Tree png
NetDUN This class allows you to add Dial-Up Networking to your application.

 

Copyright, License and Distribution

Copyright and License

This product is copyright 2000-2017 by CapeSoft Software.

You are not allowed to copy any of the other files, including but not limited to, Template (TPL) files, Library (LIB) files, net*.clw, net*.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 (trading as CapeSoft), employees of CapeSoft, and Dealers of CapeSoft products, 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.

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).

Secure Sockets Layer (SSL)

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

If you use any of the SSL features in NetSimple, 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.

It's best to distribute all DLLs into the application folder.

Deploying an SSL Client or Server

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;

The DLL files are rom OpenSSL and are included under the terms of their license.

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 this 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.
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.

The shipping file is updated from time to time, but you can update the file yourself at any time.

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.

Note: In build 7.11 of NetTalk the dependency changed from MSVCR71.DLL to MSVCR90.DLL.
Note: In build 8.56 of NetTalk the dependency changed from MSVCR90.DLL to MSVCR120.DLL.

Acknowledgements

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

This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit. This code is Copyright (c) 1998-2016 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 TinyMCE HTML Editor is Copyright by 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.

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: www.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.
[End of this document]
Return to NetTalk Documentation Index