Learning NetTalk

• I'm New to NetTalk
• Introduction to NetTalk
• Index of Jump Starts
• Class Overview
• Copyright, License and Distribution
• How to get NetTalk
• Installation Instructions
• Definitions: Client and Server
• Using NetTalk in your Applications

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:

• We've split the NetTalk documentation up into a number of smaller files to make it easier to navigate around and print. When in doubt always return to the NetTalk Index for navigating the documentation.
  
  
• JumpStarts are step-by-step guides to get the relevant functionality into your application in 10-20 minutes. If you are thinking to yourself "Hey, I've just bought this cool product and I want to see it working as quickly as possible", then these sections are for you. So keep an eye out for them.
  
  Scenarios are used to teach you how to use the NetAuto classes. While they don't specifically cover the NetSimple classes, you will find working through the scenarios will familiarize you with the class model implemented in both the NetAuto & NetSimple classes. We highly recommend that you work through at least one or two of the scenarios.
  

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.

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

2. NetSimple Classes

3. NetDUN Classes (Dial-Up Networking)

4. Web Server Classes and Templates

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.

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.

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

• All examples are found in your Clarion/3rdParty/Examples/NetTalk folder.
• There is also a list of Jump Start examples in the Jump Start section.
• There are three scenarios (with source) which can provide the basis of a NetAuto objects tutorial. These tutorials are explained here. (Even if you are only wanting to use the NetSimple classes, these scenarios will help you understand how to use NetAuto/NetSimple classes in your application).
• The NetDemo application, is the largest and most feature complete example. Make sure you have a look at this one.
• 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.

NetDemo Application

Examples
	Folder	All examples in Clarion/3rdParty/Examples/NetTalk
	Demo	Updated  This is the classic NetTalk demo application. It demonstrates the chat, Internet use, time transport, file transfer, auto close, client socket connections (NetSimple), listening server ports (NetSimple), Email send and receive, News send and receive, DIP (Dynamic IP) management, FTP, Web Client, Web Server, Ping and more. Note: This application uses HyperActive. If you do not have hyperactive you will receive a warning the first time you open the application saying "Unknown template type GloHyperActive(HyperActive)". Click OK a couple times and the application will run without HyperActive. This is not a problem. This example is the free demo that is available in an EXE at www.capesoft.com.
		NetAuto Classes
	Scenario One	This is scenario one.
	Scenario Two	This is scenario two.
	Scenario Three	This is scenario three.
	NetAuto File Get	A simple example of File Transfer using the NetFileServer and NetGetFile classes. It's even more simple than the example in NetDemo.
	NetAuto File Get And Put	An example of using File Transfer to Put Files and Get Files.
	NetRefresh	This is a simple example of NetRefresh working.
	Server DIP	This is source code for the DIPServer. It requires the CapeSoft WinEvent and looks better if you use CapeSoft's HyperActive template. It's an example but can be used to run a DIP Server. If you require the DIPServer.exe please download it from the NetTalk download page at www.capesoft.com . For more info on the DIP (client) class please look at the DIP class section. Note: If you are compiling in C55, please open the application (which will convert it from C5), Generate All, then remove the C5ASC%%L%.LIB in the Project Editor (Press the Project button). Then recompile. Note: If you are compiling in C60, please open the application, Generate All, then remove the ASCII drive from the Project Editor. Then recompile.
	Server AutoChat	This is the Automatic Chat Server (Arnold) that runs the whole time at CapeSoft. It's the Server that responds to the Internet Chat part of the netdemo.app Requires WinEvent.
	NetOptions	An example of how to use the NetOptions method call. (Includes reading and setting the Ports, NetName, Max Instances, HostName & IP address etc.)
		NetSimple Classes
	FTP Download Directory	This is the example of how to download all the files in a directory using the FTP class.
	FTP Jump Start	This is the example of the JUMP START FTP code.
	FTP Multiple Upload	FTP Multiple File Upload.
	FTP Template	FTP Template example
	LinkPoint Payment	LinkPoint Credit Card Payment Example Requires a LinkPoint account (or a trial one), a LinkPoint Certificate (real or trial) and CapeSoft's xFiles.
	NetSimple Jump Start	NetSimple JUMP START
	NetSimple Packet Boundaries & Encryption (Automatically and Manual) - Automatic is the recommended option.	NetSimple Client Server example of how to manage packet boundaries. This can be a little bit confusing at first, (that's why we made the NetAuto classes) but this example will show you how to do it. See FAQ G2 for more information about Packet Boundaries. This example also demonstrates how to use the NetDESencrypt and NetDESdecypt functions.
	NetSimple Client & Server	NetSimple Client Server Test. Uses normal TCP/IP or SSL.
	Web Jump Start	This is the example of the JUMP START Web code.
	Web Polling Agent	This is a Web poll example of checking web sites
	Web Strain	This is a Web example of looping quickly through web sites
	Web Server	Removed   This example has been replaced by the NetWebServer and _NetWebServerWorker objects. See the NetDemo application for an example of this.
	Web Server In Memory - Connection Checker.	This is an example of creating web pages in memory. Normally you would have web pages on disk, but that not always necessary.  This example requires Clarion 6.1, SelfService and WinEvent (as well as NetTalk of course). This app will check a TCP/IP connection, and will send you an email if the port can not be reached. Useful for checking: - network route reachability, - if an application is still running - or if a machine is running (try using port 139)
	Email Send Jump Start	This is the example of the JUMP START Email Send code.
	Email Send in a Process	This is an example of sending an email from within a process. (In the "SendEmail in a Process" folder).
	Email Send PDF Report	This is an example of emailing an PDF Report generated by PDFXChange. See the details in the PDFXChange section. (Note you need Tracker Software's PdfXChange (www.docu-track.com) template to run this example.)
	Email Receive Jump Start	This is the example of the JUMP START Email Receive code.
	Email Receive with Don't Download Again Option	This is the NetDemo.app's TestEmailReceive window, with an xFiles object to save the self.EmailsDoneBeforeQ to an xml file so that this queue persists.
	Server DIP	This is source code for the DIPServer. It requires the CapeSoft WinEvent and looks better if you use CapeSoft's HyperActive template. It's an example but can be used to run a DIP Server. Requirements: This requires WinEvent, NetTalk & HyperActive to compile correctly. You can get away without HyperActive, but you will definitely need WinEvent. If you require the DIPServer.exe please download it from the NetTalk download page at www.capesoft.com . For more info on the DIP (client) object please look at the DIP object section.
	SNMP Jump Start	SNMP JUMP START
	Proxy	This is an example of using NetSimple to create a Debugging Proxy Tool. Documentation can be found in the separate NetTalk Proxy Document. Requirements: This requires WinEvent, NetTalk & HyperActive to compile correctly. You can get away without HyperActive, but you will definitely need WinEvent. If you require the proxy.exe please download it from the NetTalk download page at www.capesoft.com
	Web Builder Email Send	This is an example of using WebBuilder and NetTalk. (Clarion 5.5 upwards). This example is not included in the NetTalk download, and must be downloaded separately from the NetTalk download page at www.capesoft.com .
		NetDUN Objects
	DialUp Jump Start	This is the example of the Dial-Up JUMP START DUN code.
	DialUp Hand Code	This is an example of hand coding the Dial-Up object.
		Multi-DLL Applications
	Multi DLL ABC	Multi-DLL example ABC application. This is just an example of how to use the NetTalk templates if are building a multi-DLL application.
	Multi DLL Legacy	Multi-DLL example Legacy application. This is just an example of how to use the NetTalk templates if are building a multi-DLL application.
	Multi DLL Legacy Email	Multi-DLL example Legacy application using Email.
		Legacy NetTalk Applications
	Legacy	NetLeg.app - This is a Legacy example.
	Legacy	LegEmail.app - This is a Legacy example application. If you use the Secure Email Sending, please ensure you include the SSL DLLs (see the Distribution section for details) in the application folder.
	Multi DLL Legacy	Multi-DLL example Legacy application. This is just an example of how to use the NetTalk templates if are building a multi-DLL application.
	Multi DLL Legacy Email	Multi-DLL example Legacy application using Email.
		Bonus Tools
	Proxy	This is an example of using NetSimple to create a Debugging Proxy Tool. Documentation can be found in the separate NetTalk Proxy Document.

Proxy Debugging Example Tool

 

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

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

NetDUN

This class allows you to add Dial-Up Networking to your application.

 

Copyright and License

Distribution

The full working version of NetTalk is available from:

CapeSoft Sales
Web	www.capesoft.com
Email
Telephone	+27 87 828 0123
Fax	+27 21 715 2535
Post	PO Box 511, Plumstead, 7801, South Africa

Buy Online
New product	ClarionShop
Upgrade to NetTalk 5	ClarionShop

Registered users can download the latest upgrade from the web site www.capesoft.com

Go to www.clarionshop.com to purchase and register. You will then be sent your password to unlock the product.

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

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.

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:
   • Web Client (for HTTP and HTTPS)
   • Web Server
     
   • Email Sending (SMTP)
   • Email Receiving (POP3)
   • News Sending or Receiving (NNTP)
   • FTP Client
   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.