Available in NetTalk Desktop, NetTalk Server and NetTalk Apps. Applies to Desktop (ABC or Clarion) apps.

• Introduction
• See Also
• JumpStart
• Terminology
• Upgrading
• DLL Distribution
• Get a Web Page
• Post Data to a Web Server
  • XML
  • JSON
  • Attaching a File to an Upload
• Reply Format
• Authentication
• Cookies
• Converting Examples to Clarion
• Progress Bar Control
• SOAP
• REST
• Compression
• Content-Encoding
• TLS (SSL) Connections
• Class Reference
  • NetWebClient
  • NetWebHttp
  • NetWebRoot

The WebClient Class is used to let your program interact with web servers. Those servers might be serving up files, they might be a Web Service API, or you might be sending information, or files to those servers.

The WebClient class allows your program to act as an HTTPS (or HTTP) client. The defaults for HTTPS are usually correct, and it is not usually necessary to set any extra properties for HTTPS. If the URL you are connecting to contains HTTPS:// as the protocol then the object will automatically operate in secure mode. If you are using HTTPS you will need to distribute some extra DLL and PEM files. See Deploying a TLS Client or Server.

Since SOAP and REST API Servers typically exist on top of HTTPS this class is also the one you will use if you need to communicate with a SOAP or REST server.

WebClient objects use asynchronous communications, meaning that your window will "stay alive" as the communications happens in the background. This means that the WebClient object must be on a procedure with a window, not a source procedure. (You can however hide the window if you like).

The most common request methods are Get and Post (although there are quite a few others supported as well.)

Because the code is asynchronous, when you make a request the code carries on to the next line before the result arrives. When the result has arrived from the server then the PageReceived method is called (and the ThisPage property contains the returned header and data.) If a network error occurs then the ErrorTrap method will be called instead. If the remote server does not like your request (for whatever reason) and returns an error then that error will flow into PageReceived , not ErrorTrap. So your "handle reply" code goes into PageRecieved, not into the code immediately following the code.

This approach is non-blocking, meaning that your UI does not "freeze" while the communication to the remote server (which might take a while) takes place.

Many other classes are related to, or depend on, the WebClient class.

• Web Sockets

1. Add the NetTalk Global Extension to your application
2. On a Window, add a NetTalk Object Extension.
3. Choose a name for the object (this document will use the name net) and set the base class to NetWebClient

Name	Description
HTTP	HyperText Transfer Protocol - this is the "language" of web servers - it is the building block of all communications between a WebServer and a WebClient. (Your browser is an example of a WebClient)
HTTPS	The same as HTTP, but over a secure connection. Connections are secured using TLS.
TLS	Transport Layer Security. This used to be known as SSL (Secure Sockets Layer.)
Host	The URL or IP address of the Web server you want to talk to.
Port	The port number you are connecting to. The usual value is 80 for HTTP sites and 443 for Secure (TLS) sites.
GET, POST, PUT, PATCH, DELETE, QUERY, OPTIONS	These are the typical commands you will use to interact with a web server. Also known as "HTTP VERBS" these are the basic commands of the HTTP protocol.

If you are upgrading from an earlier version of NetTalk to NetTalk 14 or later and you are getting errors then read this section for required, or suggested, changes.

1. In NetTalk 14.23 a new property (OptionDontRedirectHTTPtoHTTPS) was introduced to the WebClient object. This property is set to true by default. This means the client will no longer auto-redirect from an HTTP request to an HTTPS location. This will assist developers in spotting where HTTP is used incorrectly, and fix it to the correct location. This is important because the HTTP request may contain sensitive information, like API keys, and making the first request as HTTP exposes this information to packet sniffers. In the past this URL error (using HTTP) would go unnoticed because the server would likely return a redirect, and the client would silently just go to the correct URL.
2. In NetTalk 10 the Page property (which was a STRING) is now renamed as ThisPage, and is declared as a STRINGTHEORY object.
   This will affect code you may have embedded in the PageReceived method.
   The contents of the ThisPage property can be retrieved using ThisPage.GetValue(). For example
   
   whatever(self.page)
   
   would be replaced with
   
   whatever(self.thispage.GetValue())
   
   In some cases (notably when calling xFiles.Load) the self.page parameter was being passed as a pointer. In these cases the code is replaced with
   
   whatever(self.thispage.GetValuePtr())
3. The PageLen property has been removed. Use self.ThisPage.Length() instead.
4. The _Command property (String) has been replaced with _CommandText (StringTheory.)
   Use _CommandText.GetValue()
5. The _PageContentLen property has been renamed to PageContentLen.
6. The _GetContentType method has been renamed to GetContentType.
7. The _HTTPVersion property has been renamed to HTTPVersion. As from version 9.20 this property defaults to 1.1 not 1.0.
   If you have this line in your embed code;
   net._HTTPVersion = 'HTTP/1.1'
   then you can just remove the line.

See Deploying a TLS Client or Server

Remember also to ship zlibwapi.dll.

The simplest command to a web server is a simple GET. (The FETCH method works exactly the same as the GET - the two are synonyms of each other - you can use that method instead if you prefer.)

The basic syntax of the GET method is a single parameter which is the URL of the page (or file) to fetch from the server. For example;

net.Get('capesoft.com')

If the site is using HTTPS then simply add that to the front of the URL

net.Get('https://capesoft.com')

Parameters can be added to a URL in the usual URL encoded way;

net.Get('capesoft.com?products=all&amazing=yes')

An even easier approach, especially when dealing with multiple parameters is to use the SetValue method;

net.SetValue('name','value')
net.SetValue('anothername','anothervalue')
net.get('capesoft.com')

This approach takes care of things like URL encoding and so on, so is a lot easier.

The command will begin executing in the background. When the response has arrived then the PageRecieved method will be called. The contents of the response will be in the ThisPage property. The response will include the header and the response text. To remove the header part use the RemoveHeader method.

You can save the response to a file, with or without the header. To save it with the header;

net.ThisPage.SaveFile('filename')

To save it without the header

net.RemoveHeader()
net.ThisPage.SaveFile('filename')

When sending data to a server the most common method that you are required to use is Post. Post is similar to Get in that you use a simple URL as the parameter, but a Post can also send Data to the server as part of the request.

For example

net.Post('capesoft.com',data)

The data parameter can be either a string, or a StringTheory object.

The format of data depends on what the server is expecting - it might be json, or xml, or indeed anything.

The default format is form-encoding. If the post you are doing takes form encoded data, then, as before, use the SetValue method to add fields to the request. For example;

net.SetValue('CustomerName','Charlie')
net.SetValue('Company','Capesoft')

Using this method you can attach files to the upload as well

net.SetValue('somefile','c:\temp\a.pdf',net:AsFile)

When doing a post in this way, just leave the second parameter to the Post method blank, or omit it.

net.Post(url)

XML

JSON

Attaching a File to an Upload

Some requests will require that you tell the server what format the reply should be in. This is done using the SetAccept method.

net.SetAccept('xml')

Some web servers make use of BASIC or DIGEST authentication. This is authentication which typically requires 2 parts; the username and the password, and the authentication is automatically added into the header for you.

You can easily add authentication to your request by adding the following line before your call to GET or POST.

For Basic Authentication you would add

net.Authorization = net.CreateAuthorizationString(User,Password,Net:WebBasicAuthentication,true)

And for Digest Authentication you would add

net.Authorization = net.CreateAuthorizationString(User,Password,Net:WebDigestAuthentication,true)

Cookies are variables sent to you by a web server. When making subsequent requests to the same server then (usually) the cookies should be sent with the reply.

NetTalk includes the ability to parse cookies from incoming replies, and include them (when talking to the same host) with subsequent requests by the same object. To turn this ability on set
net.OptionAutoCookie = true
before the first call to the server.

In additional you can add other cookies to the request using the SetCookie method.

net.SetCookie('whatever','somevalue')

If you are talking to an API server, (and you are lucky) then that service will have some documentation of the methods and parameters and so on that the service requires. Translating this documentation into Clarion can take some practice and understanding.

CURL

When doing a large upload, or download, it's useful for the user to see a progress bar so they get some idea of how far it still has to go. The NetWebClient class has support for progress controls built in.

To use the progress control simply set the ProgressControl property of the object to the Field Equate of the progress control on your window. For example;

net.ProgressControl = ?progress1

The control will be updated automatically. It is updated as incoming packets are received for downloads and at 1.5 second intervals for uploads.

Note that when doing a PUT or POST request from a web client to a web server there are two distinct events which are monitored by the progress bat. The first is the upload of the Post data. The second is the download of the reply. So with a PUT or POST command the user may see the progress control run "twice". Of course one (or both) of the two operations may be very fast.

SOAP is a particular form of XML. So a SOAP server is a web server which expects incoming data to be formatted as XML (and specifically SOAP XML). SOAP servers typically only support the GET or POST methods.

The data returned is in XML format.

Formatting requests for SOAP 1.1 and SOAP 1.2 is slightly different.

SOAP 1.1

SOAP 1.2

REST is an alternative to SOAP. It serves the same purpose but is JSON based rather than XML based. REST is also a lot less formal than SOAP - so there's a lot more variety between servers, but equally it's a lot simpler to work with so is preferred by many developers of both servers and clients.

One of the big differences between SOAP and REST is that REST often applies meaning to the HTTP verb used - so in addition to GET and POST it is also common to make use of the PUT and DELETE methods. PUT has the same parameters as POST and DELETE typically has the same parameters as GET.

net.SetContentType('json')
net.SetAccept('json')
net.Post(url,data)

Advanced

It is very common for the server to send you the result in a compressed format. This is on by default, and invisible to you as the programmer. The NetWebClient class sets a header (Accept-Encoding: gzip) which tells the server that compression is supported. If the server supports it then it will send you the resulting page compressed. This is on by default (as long as the zlibwapi.dll file is in the exe folder.) Again, this is invisible to you and you are not even aware it is happening.

If you want to prevent this behaviour by the client, then call

net.AcceptEncoding = 'plain'

Content-Encoding

Connecting over TLS using the HTTPS protocol is not much different from connecting over non-secure connections using HTTP. The WebClient class sits above the connection itself, therefore it has no special code to deal with the connection.

The WebClient class does however inherit from the NetSimple class and so the TLS related properties there are in use here as well.
The following table contains some of the most useful properties, however this list is not exhaustive - see the NetSimple documentation for a complete list of properties.

Property	Description
SSL	Set to true if the connection is over, or will be over, TLS. You do not need to set this, it is set automatically if the URL being requests begins with HTTPS.
SSLMethod	The SSL (TLS) version to use when connecting to the server. The default value is NET:SSLMethodTLS. For more options on this method see the NetAll.Inc file.
SSLCertificateOptions. ServerName	If set then this is an alternate test for the server certificate name. Usually the name has to match the hostname you are connecting to, but if you know the certificate will have a wrong (but fixed) name then you can enter the expected name here.
SSLCertificateOptions. DontVerifyRemoteCertificateCommonName	If set to true then the common name of the server certificate is not matched to the server the client is connecting to. This setting should be used with caution - it allows for a man-in-the-middle attack.
SSLCertificateOptions. DontVerifyRemoteCertificateWithCARoot	If set to true then the server certificate is not tested against the caroot.pem file to see if it is trusted. Use this setting with caution, if set then the communication with the server will be encrypted, but the server itself is not trusted. This setting also allows for a man-in-the-middle attack to take place.
CertificateFile	The location of a client-side certificate file. This is very rarely used with web servers.
PrivateKeyFile	The location of a client-side private key file. This is very rarely used with web servers.

• NetWebClient
• NetWebHttp
• NetWebRoot

NetWebClient

Delete

DeleteCookie

Get / Fetch

PageReceived

Patch

Post

Put

RemoveHeader

SavePage

SetAccept

SetAllHeadersDefault

SetContentType

SetValue

Start

ClassNetWebHttp

CreateAuthorizationString

CreateAuthorizationStringOAuth1

CreateGMTDate / CreateUTCDate

DontSendCookie

GetContentType

SetCookie

NetWebRoot

NormalizeURL

GetHeaderField