NetTalk WebClient
Available
in NetTalk Desktop, NetTalk Server and NetTalk Apps. Applies to Desktop
(ABC or Clarion) apps.
Introduction
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.
See Also
Many other classes are related to, or depend on, the
WebClient class.
JumpStart
- Add the NetTalk Global Extension to your application
- On a Window, add a NetTalk Object Extension.
- Choose a name for the object (this document will use the name net) and set the base class to NetWebClient
Terminology
| 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. |
Upgrading
If you are upgrading from an earlier version of
NetTalk to NetTalk 10 or later and you are getting errors then read this
section for required, or suggested, changes.
- 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())
- The PageLen property has been removed.
Use self.ThisPage.Length() instead.
- The _Command property (String) has been
replaced with _CommandText (StringTheory.)
Use _CommandText.GetValue()
- The _PageContentLen property has been
renamed to PageContentLen.
- The _GetContentType method has been
renamed to GetContentType.
- 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.
DLL Distribution
Get a Web Page
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')
Post Data to a Web Server
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
When sending a Post to a WebService the data may
need to be in XML format. Use your
favorite XML creation tool to format this text.
You will need to set the
Content-Type
header to be XML so that the server knows the data is in XML format.
data = '<some xml>'
net.SetContentType('xml')
net.post(url,data)
JSON
When sending a Post to a WebService the data may
need to be in JSON format. Use your
favorite JSON creation tool to format this text.
You will need to set the
Content-Type
header to be JSON so that the server knows the data is in JSON format.
data = '{{some json}'
net.SetContentType('json')
net.post(url,data)
Attaching a File to an Upload
There are three common ways of uploading a file to a
web server.
- Inside the XML data. (Typically to a WebService API)
- Inside the JSON data. (Typically to a WebService API)
- As part of a Multipart/form-data post. (Typically mimicking a POST
from a browser's File Upload button.)
If the file is included in XML then it is typically Base64 encoded,
and included in the XML as a simple text field. Consult your XML tool
documentation if this is the approach the server requires.
If the file is included in JSON then it is typically JSON Encoded and
included in the JSON as a simple text field. Consult your JSON tool
documentation if this is the approach your server requires.
If you are mimicking a Post from a browser, and uploading the file as
a multipart form-data encoded Post, then use the SetValue method to
add one or more fields (including the file) to the data prior to
calling the Post method, as described above.
Reply Format
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')
Authentication
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
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')
Converting Examples to Clarion
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
If you are
really lucky then the service
includes a CURL example. CURL is a command line tool which exists on all
computers (Windows, Linux, Mac etc) which is basically a Web Client.
Since it is a command line tool it has a well defined syntax. And
because the syntax is well defined, it can easily be translated into any
programming language.
If you go to
capesoft.com/curlcode
you can enter the CURL example there, and then the NetTalk client code
will be generated for you.
Progress Bar Control
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
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
In SOAP 1.1 an additional header is required in the
actual WebClient request. The SOAPAction property is used for this. The
SOAPAction header is set to the name of the server, and the name of the
method being called. For example;
net.SetContentType('soap11')
net.SetAccept('xml')
net.SOAPAction = clip(Server) & '/dbCustomers'
net.Post(url,data)
SOAP 1.2
SOAP 1.2 does not require the custom header to be
set, but the content type does need to be set.
net.SetContentType('soap12')
net.SetAccept('xml')
net.Post(url,data)
REST
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
REST is less structured than SOAP, so pretty much
anything goes. In some extreme cases the format of the request is
different to what is typical for a WebClient. For example a GET request
might include data like a POST and so on. For this reason all the
NetTalk methods (GET, PUT, POST, DELETE) support a second "data"
parameter. This parameter can be either a String or a StringTheory
object.
Compression
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
Far less common is the ability of the client to send
compressed data to the server. Most servers either do not support, or
are not configured, to accept compressed data. There is also no easy way
for the client to discover if the server supports it or not. So
client-side compression is typically only useful when you know the
server you are talking to supports it.
From NetTalk 14, the NetTalk server does support client-side
compression. So when you are communicating from a NetTalk Client to a
NetTalk Server, compression of the data is supported
[1],
and this can have a dramatic effect on transfer times. Any time you
control both the server and the client, this feature can substantially
improve transfer times, and reduce data costs.
This feature is activated in the client by calling;
net.SetClientCompressed(true)
before the call to POST. This sets a header for you, which is sent to
the server as
Content-Encoding: gzip
Note 1: The server
needs to have this feature turned on. Read more about the server side of
this feature at
Client
Side Compression.
TLS (SSL) Connections
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. |
Class Reference
NetWebClient
Derivation
- NetWebClient ( NetWww.Inc / NetWww.Clw
)
Properties
| Property |
Description |
| AcceptEncoding |
Defaults to gzip - Tells the server that the response may be
compressed using the gzip algorithm. Responses that arrive
gzipped are automatically unzipped before being passed to the
PageReceived method. |
| AsyncOpenTimeout |
The amount of time, in hundreds of a second, to wait before
an attempt to Open a request fails. The default value for this
setting is 900, or 9 seconds. |
| Busy |
If this property is set then a response is being received
from the web server. |
| BytesWritten |
the number of bytes written to the disk by the SavePage
method. |
| CacheControl |
Allows you to set the Cache-Control header of a request
(before making the request). |
| CanUseProxy |
Set to true if this object can access the URL via a Proxy
server. |
| CustomHeader |
Allows you to add a custom header to the request. For
example;
net.customheader = 'xxx-whatever:
good-to-go' |
| HeaderLen |
The length of the header part of the received page. |
| HeaderOnly |
If this is set to true then the next request made to the
server will only fetch the Header part of the response from
the server. This allows you to determine the capabilities of
the server, as well as (possibly) the prospective size of the
response to the request, before asking for the actual
response. |
| HTTPVersion |
As from build 9.20 the default for this is HTTP/1.1
- Previously it was HTTP/1.0. |
| FormEncodeType |
Set to multipart/form-data if
the form will be submitted as a multipart form. |
| OptionAutoCookie |
If set to true then incoming
cookies are automatically added to the queue and sent out with
subsequent requests. |
| OptionDontRedirect |
If set to false (the default)
then a Redirect response (30x) from the server will
automatically be followed to the specified URL. |
| OptionDontSetCookieOnRedirect |
If true stops the SetCookie
being put into the Cookie on Redirection |
| OptionFinishOnEndHTMLTag |
This option (if set to true)
will cause PageReceived to be
called if the page we are receiving has no content-length, and
the last 7 characters are </html> |
| PageContentLen |
The size of the incoming response from the server - if this
header has been set by the server before sending. |
| PageChunked |
Is set to true if the response from the server is in chunked
format. |
| Progress |
A property that contains the progress percentage (from 1 to
100) of the incoming reply from a server. |
| ProgressControl |
A property that contains the FEQ of a Progress bar control
on the window. If set then uploads and downloads will
automatically give progress feedback to the user as the upload
and download happens. For more information see Progress
Bar Control. |
RangeStart
Range End |
Allows the client to set a range of bytes (0 based, not 1
based) from the file being fetched.
Not all servers support ranges. If a server returns a header;
Accept-Ranges: none
then it definitely does not support ranges. If it
returns a header
Accept-Ranges: bytes
then it definitely does support ranges. If it returns
neither of these then it may, or may not, support ranges.
A NetTalk 10 server supports range requests for static files,
but not for dynamically generated pages. |
| SOAPAction |
Set this to the value of the SOAPAction
header as required by SOAP 1.1 servers, before doing
a request. See SOAP. |
| ThisPage |
A StringTheory object containing the response from the
remote server. This property is set when the PageReceived
method is called. |
Methods
| Method |
Description |
| CreateAuthorizationString |
See NetWebHttp
CreateAuthorizationString |
| Delete |
Sends a DELETE request to a web server. |
| DeleteCookie |
Deletes a cookie from the cookie queue. |
| ErrorTrap |
See NetSimple ErrorTrap. |
| Get |
Sends a GET request to a web server. |
| Fetch |
See Get. |
| PageReceived |
Is called when a response is received from the server. |
| Patch |
Sends a PATCH request to a web server. |
| Post |
Sends a POST request to a web server. |
| Put |
Sends a PUT request to a web server. |
| RemoveHeader |
Removes the header part of a response from the server. |
| SavePage |
Saves the data part of the page, not the header, to a file
on the disk. |
| SetAccept |
Sets the Accept header for the outgoing request |
| SetAllHeadersDefault |
Sets all the headers values for requests back to their
default state. |
| SetContentType |
Sets the Content Type header for the outgoing request. |
| SetCookie |
See NetWebHttp SetCookie |
| SetValue |
Sets a Form Field value in preparation for doing a Post or
Put. |
| Start |
Sets the object back to a virgin state. |
Delete
Delete (String
p_Url,[String p_PostString | StringTheory p_PostString])
Description
Makes a call to the server using the DELETE verb.
Parameters
| Parameter |
Description |
| p_Url |
The fully formed URL containing the host, path, and resource
of the parameters. URL encoded parameters can also be used here. |
| p_PostString |
An optional string (or StringTheory object) which is sent to
the server as part of the request. This data is sent as "Post
Data" (ie after the HTTP header) even though a DELETE typically
does not expect Post data. This parameter is only rarely used
when talking to a server that requires Post data with a DELETE
request. |
Return Value
The method returns nothing.
See Also
Post,
Put,
Get,
Patch
DeleteCookie
DeleteCookie
(String p_Name)
Description
Deletes a cookie from the cookie queue.
Parameters
| Parameter |
Description |
| p_Name |
The name of the cookie to delete. |
Return Value
The method returns nothing.
See Also
SetCookie
Get / Fetch
Get (String
p_Url,[String p_PostString | StringTheory p_PostString])
Fetch (String p_Url)
Description
Makes a call to the server using the GET verb. Either the GET or FETCH
method name can be used, they do the same thing.
Parameters
| Parameter |
Description |
| p_Url |
The fully formed URL containing the host, path, and resource
of the parameters. URL encoded parameters can also be used here. |
| p_PostString |
An optional string (or StringTheory object) which is sent to
the server as part of the request. This data is sent as "Post
Data" (ie after the HTTP header) even though a GET typically
does not expect Post data. This parameter is only rarely used
when talking to a server that requires Post data with a GET
request. |
Return Value
The method returns nothing.
See Also
Post,
Put,
Delete,
Patch
PageReceived
PageReceived ()
Description
Is called when a response is received from the server. The whole
response (including the header and data) is in the ThisPage property. A
request is sent to the server using one of the request methods,
Get,
Post,
Put,
Delete or
Patch.
This is one of the most important embed points in the class because it
determines what you do with the response from the server.
Examples
To remove the header at this point call the RemoveHeader method.
self.RemoveHeader()
something = self.ThisPage.GetValue()
To save the page (with the header removed, even if you have not called
RemoveHeader) call the SavePage method.
self.SavePage(filename)
To save the page, with the header included
self.thispage.saveFile(filename)
Return Value
The method returns nothing.
See Also
Get,
Put,
Delete,
Post,
Patch,
RemoveHeader,
SavePage
Patch
Patch (String
p_Url,[String p_PostString | StringTheory p_PostString])
Description
Makes a call to the server using the PATCH verb.
Parameters
| Parameter |
Description |
| p_Url |
The fully formed URL containing the host, path, and resource
of the parameters. URL encoded parameters can also be used here. |
| p_PostString |
An optional string (or StringTheory object) which is sent to
the server as part of the request. This data is sent as "Post
Data" - ie after the HTTP header. |
Return Value
The method returns nothing.
See Also
Get,
Put,
Delete,
Post
Post
Post (String
p_Url,[String p_PostString | StringTheory p_PostString])
Description
Makes a call to the server using the POST verb.
Parameters
| Parameter |
Description |
| p_Url |
The fully formed URL containing the host, path, and resource
of the parameters. URL encoded parameters can also be used here. |
| p_PostString |
An optional string (or StringTheory object) which is sent to
the server as part of the request. This data is sent as "Post
Data" - ie after the HTTP header. |
Return Value
The method returns nothing.
See Also
Get,
Put,
Delete,
Patch
Put
Put (String
p_Url,[String p_PostString | StringTheory p_PostString])
Description
Makes a call to the server using the PUT verb.
Parameters
| Parameter |
Description |
| p_Url |
The fully formed URL containing the host, path, and resource
of the parameters. URL encoded parameters can also be used here. |
| p_PostString |
An optional string (or StringTheory object) which is sent to
the server as part of the request. This data is sent as "Post
Data" - ie after the HTTP header. |
Return Value
The method returns nothing.
See Also
Get,
Post,
Delete,
Patch
RemoveHeader
RemoveHeader ()
Description
Removes the header part of the response from the
thispage
property.
Example
In the
PageReceived method.
self.RemoveHeader()
something = self.ThisPage.GetValue()
Return Value
The method returns nothing.
See Also
PageReceived
SavePage
SavePage (string
p_FileName)
Description
Saves the data part, not the header, to a file on the disk.
Parameters
| Parameter |
Description |
| p_FileName |
The name, and path, of the file to save. If the file exists it
will be overwritten. |
Example
In the
PageReceived method.
self.SavePage('c:\temp\a.png')
Return Value
The method returns nothing. The
BytesWritten property
is updated to indicate the number of bytes written to the disk.
See Also
PageReceived
SetAccept
SetAccept(String
pType)
Description
Sets the Accept_ property (and hence the Accept header) for the outgoing
request.
The Accept header tells the server what format to use for the reply. In
most cases this header is ignored, unless the server has a choice of
what to return. For example a Web Service API may allow you to choose
between an XML or JSON response.
Parameters
| Parameter |
Description |
| pType |
The name of a file, or extension, which indicates the type of
data being requested. Most often is one of
'xml', or 'json' or left
as the default value. |
Example
To set it to be XML
net.SetAccept('xml')
To set it to be JSON
net.SetAccept('json')
Return Value
The method returns nothing.
See Also
SetContentType
SetAllHeadersDefault
SetAllHeadersDefault()
Description
Sets all the headers for a request back to their default state.
Example
net.SetAllHeadersDefault()
Return Value
The method returns nothing.
See Also
Start
SetContentType
SetContentType
(String pType)
Description
Sets the ContentType property (and hence the Content-Type header) for
the outgoing request.
The Content-Type header tells the server what format is being used for
the data attached to the request. This applies to Post data, typically
sent with the
Post or
Put
method.
If this method is not called then the content-type will default to
blank, which is then either set to
application/x-www-form-urlencoded
or
multipart/form-data if the data includes
a disk file.
Parameters
| Parameter |
Description |
| pType |
The name of a file, or extension, which indicates the type of
data being used in the request. Most often is one of
'xml', or 'json' or left
as the default value. |
Example
To force it to be
application/x-www-form-urlencoded
net.SetContentType('form')
To force it to be
multipart/form-data
net.SetContentType('multipart')
To set it to be XML
net.SetContentType('xml')
To set it to be JSON
net.SetContentType('json')
Return Value
The method returns nothing.
See Also
SetValue,
Post,
Put,
SetAccept
SetValue
SetValue (String
pName, String pValue, Long pFile=0, <String pContentType>,
<String pCustomHeader>)
Description
When a Post or Put method is sent to a server then additional data is
also usually sent to the server.
If the Post data format is multipart/form-data or
application/x-www-form-urlencoded then the values (including files) can
be added to the post using this method.
Parameters
| Parameter |
Description |
| pName |
The name of the field. |
| pValue |
The value of the field. If the value is a file attachment on
the disk then set this to be the path, and filename, of the file
on the disk. |
| pFile |
If the value field contains a filename then set this to true.
|
| pContentType |
If the field has a custom Content-Type then set it here. If
omitted then the content type is set based on the extension of
the filename. |
| pCustomHeader |
If a custom header has to be included with the field then set
it here. |
Example
net.SetValue('name','nettalk')
net.setvalue('invoice','c:\temp\invoices.pdf',true) ! content-type is
application/pdf
net.setvalue('logo','c:\temp\logo',true,'bmp')
Return Value
The method returns nothing.
See Also
Post Data to a Web Server
Start
Start()
Description
Sets all the object back to a virgin state.
Example
net.start()
Return Value
The method returns nothing.
See Also
SetAllHeadersDefault
ClassNetWebHttp
Derivation
- NetWebHttp ( NetHttp.Inc /
NetHttp.Clw )
Properties
| Property |
Description |
| Authorization |
Contains the header used to authenticate with the server,
based on the user name and password. |
| ProxyAuthorization |
Contains the header used to authenticate with the proxy
server, based on the user name and password. |
| AuthUser |
The UserName used in the most recent call to CreateAuthorizationString |
| authPassword |
The Password used in the most recent call to CreateAuthorizationString |
Methods
| Method |
Description |
| CreateAuthorizationString |
Generates an authorization string based on a user name and
password. Supports Basic and Digest authentication. |
| CreateAuthorizationStringOAuth1 |
Generates an authorization string based on tokens for
communicating with an OAuth1 Web Service. |
CreateGMTDate
CreateUTCDate |
Create a date time stamp of the form Fri, 8 Oct 2004
16:54:48 GMT |
| DontSendCookie |
Delete a cookie from the cookie queue |
| GetContentType |
Return the appropriate content-type value based on a
filename |
| SetCookie |
Add, or change, a cookie in the cookie queue. |
CreateAuthorizationString
CreateAuthorizationString
(string p_UserName, string p_Password, long p_AuthorizationMethod,
long p_Options=0)
Description
Generates an authorization string based on a user name and password.
Authorization strings are used in HTTP headers when authenticating with
the server as either BASIC or DIGEST authentication.
If given a choice, then BASIC authentication is recommended for servers
connected to over HTTPS - DIGEST authentication is recommended for
servers connected to over HTTP.
Parameters
| Parameter |
Description |
| p_Username |
The user name to include in the authorisation string. |
| p_Password |
The password to include in the authorisation string. |
| p_AuthorizationMethod |
One of Net:WebBasicAuthentication
or Net:WebDigestAuthentication |
| p_Options |
st:NoWrap - do not wrap the result. Recommended. (Basic
Authentication Only)
net:proxy - authenticate against proxy server - (Digest Only) |
Return Value
The method returns the Authentication string. It is then most commonly
assigned to the
Authorization property.
When this method is called the AuthUser and Password properties are
automatically updated to these values.
Example
net.Authorization =
net.CreateAuthorizationString(User,Password,Net:WebBasicAuthentication,true)
See Also
Authentication
CreateAuthorizationStringOAuth1
CreateAuthorizationStringOAuth1
(String pVerb, String pUrl, AuthParametersGroup pParms)
Description
Used by the OAuth class to generate the Authorization header string for
OAuth 1 requests.
Parameters
| Parameter |
Description |
| pVerb |
The HTTP verb being used. For example, GET, POST, PUT, DELETE |
| pUrl |
The URL being connected to |
| pParms |
a AuthParametersGroup. (Same as a
oAuthParametersGroup). Typically passed to, and back from
the NetOAuth class. |
Return Value
The method returns the Authentication string. It is then most commonly
assigned to the
Authorization property.
Example
s group(AuthParametersGroup).
code
s = whatever
self.Authorization =
self.CreateAuthorizationStringOAuth1('GET',pRequestTokenURL, s )
See Also
OAuth
CreateGMTDate / CreateUTCDate
CreateGMTDate
(long p_Date=0, long p_Time=0)
CreateUTCDate (long p_Date=0, long p_Time=0)
Description
Create a date time stamp of the form Fri, 8 Oct 2004 16:54:48 GMT.
Local time is automatically converted to UTC time when generating the
timestamp.
Parameters
| Parameter |
Description |
| p_Date |
The date of the time stamp. If omitted, or 0, then defaults to
today. |
| p_Time |
The time of the time stamp. If omitted, or 0, then defaults to
today. |
Return Value
The method returns a string of the form Dayname, DayNumber MonthName
Year Time GMT
See Also
DontSendCookie
DontSendCookie
(String p_Name)
Description
Deletes a cookie from the cookie queue. This method is used by the
WebServer only, for the WebClient see DeleteCookie.
Parameters
| Parameter |
Description |
| p_Name |
The name of the cookie to delete. |
Return Value
The method returns nothing.
See Also
SetCookie
GetContentType
GetContentType
(string p_FileName)
Description
Return the appropriate content-type header value based on a filename.
Parameters
| Parameter |
Description |
| p_FileName |
The name of the file (or extension) to return the content-type
for. |
Return Value
The method returns a content-type string suitable for being applied to
the content header.
Example
s =
net.GetContentType('json')
s = net.GetContentType('c:\temp\whatever.jpg')
See Also
Post Data to a Web Server
SetCookie
SetCookie (String
p_name, String p_Value, <Long p_Date>, <Long p_Time>,
<Long p_Secure>, <String p_Path>, <String p_Domain>,
Long p_HttpOnly=0)
Description
Adds a cookie to the cookie queue. The cookies in the cookie queue are
automatically included on the next (and subsequent) calls to the server.
Parameters
| Parameter |
Description |
| p_Name |
The name of the cookie to add. |
| p_Value |
The value of the cookie to add. |
| p_Date |
(server only) The date on which the cookie expires. |
| p_Time |
(server only) The time on which the cookie expires. |
| p_Secure |
(server only) If set then the cookie will only be used on
secure (HTTPS) connections. |
| p_Path |
(server only) The Path attribute for the cookie. |
| p_Domain |
(server only) The Domain attribute of the cookie |
| p_HttpOnly |
(server only) If set then the cookie is only available to the
browser, and not to JavaScript running in the browser. |
Return Value
The method returns nothing.
See Also
For more information on cookie attributes see
Wikipedia.
Cookies
NetWebRoot
Derivation
- NetWebRoot ( NetHttp.Inc / NetHttp.Clw )
Methods
| Method |
Description |
| NormalizeURL |
Changes \ in a URL to /, makes sure the parameter-separator
is a ?, and all the other parameters are separated by a ? |
| GetHeaderField |
Get a header field value from a request or a response. |
NormalizeURL
NormalizeURL
(String pURL)
Description
Changes \ in a URL to /, makes sure the parameter-separator is a ?, and
all the other parameters are separated by a ?
Parameters
| Parameter |
Description |
| p_Url |
The fully formed URL containing the host, path, and resource
of the parameters. URL encoded parameters can also be used here. |
Return Value
The method returns a string containing the normalized URL.
See Also
GetHeaderField
GetHeaderField
(string p_SearchString, StringTheory p_MainString | *string
p_MainString, long p_StartPos=1, long p_EndPos=0, long
p_CaseInsensitive=true)
Description
Get a header field value from a request or a response.
Parameters
| Parameter |
Description |
| p_SearchString |
The header value to look for. |
| p_MainString |
The string, or StringTheory object, containing the request, or
response. |
| p_StartPos |
The start position in the string to commence the search. If
omitted, or 0, then the start of the string is used. |
| p_EndPos |
The end position in the string to search for the header. If
omitted or 0 then the end of the string is used. |
| p_CaseInsensitive |
If true (the default value) then
the header name is considered to be case insensitive. |
Return Value
The method returns a string containing the value of the header field. If
the header is not found then a blank string is returned.
Example
result = self.GetHeaderField
('content-length',self.thispage)
[End of this document]
