NetAddressLookup(String pIpStr)

Description

 Performs a reverse DNS lookup. In other words, given an IP address it searches for an entry in the DNS database which matches that address. Since one address can be used by multiple entities this function is inherently unreliable. It should be used as a "hint" only, not as canonical truth.



Parameters

Parameter	Description
pIpStr	A string containing an IP address in text form.

Return Value

A DNS name. If no name is found then a blank string is returned.

Notes

Only available in Windows Vista or later.

Examples

host = NetAddressLookup('54.82.121.220')

See Also

NetDNSLookup .

NetDecryptString(*string pInData, long pDataLength, String pPassword, long pAlgorithm=NET:CALG_AES_256, long pHashAlgorithm=NET:CALG_SHA_256, Long pCipherMode=NET:CRYPT_MODE_CBC, Long pPadding=NET:PKCS5_PADDING,<String pIV>,<String pTag>)

Description

This function decrypts a string, using a password, and returns the decrypted string. The original string is unaltered.
The decrypted string size will always be the same as, or less than, the encrypted string size.

Parameters

Parameter	Description
pInData	A pointer to the data to be decrypted. The original data is not altered.
pDataLength	The length of the data to decrypt.
pPassword	The password to use for the decryption. If pHashAlgorith is set to net:CALG_NOHASH then the password must be the correct length for the encryption algorithm. For AES256 this is 32 bytes.
pAlgorithmn	The Algorithm to use. Currently supported algorithms are; NET:CALG_AES_256
pHashAlgorithm	The Hashing Algorithm to use on the Password, before the encryption happens. Hashing a password improves the strength of the password. Algorithms supported by NetMakeHash are supported here.
pCipherMode	The cipher mode to use. Currently supported options are; NET:CRYPT_MODE_CBC, NET:CRYPT_MODE_GCM If you are using NET:CRYPT_MODE_GCM then you MUST pass the pTag parameter.
pPadding	The Padding mode to use. Currently supported options are; NET:PKCS5_PADDING
pIV	The Initialization Vector to use. The length of the Init Vector is determined by the algorithm. For AES 256 it's 16 bytes long. Strings that are too long are clipped. Strings that are too short are padded with chr(0). If not passed (or passed as a blank string) then a string of null characters (chr(0)) is used.
pTag	If you are using NET:CRYPT_MODE_GCM then you MUST pass the pTag parameter. It is not necessary in other cases. This is a String(16) which was populated when the NetEncryptString function was called. If you fail to pass this parameter in, or if the value does not match the value created by NetEncryptString, then the decryption will fail.

Return Value

Returns the decrypted string. If the function fails a blank string is returned.

Examples

str  string(100)
enc  string(112)
dec  string(100)
  code
  str = 'NetTalk is Amazing'
  enc = NetEncryptString(str,len(str),'1234')
  dec = NetDecryptString(enc,len(enc),'1234')

st  StringTheory
  code
  st.SetValue('NetTalk Is Amazing')
  st.SetValue(NetEncryptString(st.GetValuePtr(),st.Length(),'1234'))
  st.SetValue(NetDecryptString(st.GetValuePtr(),st.Length(),'1234'))

See Also

NetEncryptString, NetEncryptStringAES, NetDecryptStringAES

NetDecryptStringAES(String pInData, String pPassword)

Description

Same as calling NetDecryptString, with all optional parameters set to default, and the Algorithm set to NET:CALG_AES_256.
Parameters

Parameter	Description
pInData	The data to decrypt.
pPassword	The password

Return Value

Returns the decrypted string. If the function fails a blank string is returned.

Examples

dec = NetDecryptStringAES(clip(someencrypteddata),'1234')

See Also

NetEncryptString, NetEncryptStringAES, NetDecryptString

NetDnsLookup(string pHostName,*Long pFamily)

Description

Does a Domain Name Service (DNS) lookup, resolving a DNS name into an IP Address.

Parameters

Parameter	Description
pHostName	A DNS name, or IP address. For example capesoft.com, 127.0.0.1 or ::1
pFamily	One of Net:IPvAuto, Net:IPv4, Net:IPv6. If pFamily is Net:IPvAuto then the function attempts to resolve an IPv4 address first. If none exists then it attempts to resolve as an IPv6 address. If it is set as Net:IPv6 or Net:IPv4 then it will limit the look to that address.

Return Value

A string containing the IP address.

If the HostName is already an IP address (ie something like 127.0.0.1 or ::1) and it matches the Family parameter (or the Family parameter is Auto), then the same  hostname is returned.

If the pFamily parameter is Net:IpvAuto, then it is changed to either Net:IPv4 or Net:IPv6, depending on how the address resolved.

If the HostName is valid (and appears in the DNS Database), but does not contain a valid A or AAAA record, then the text '<no data>' is returned.

If the hostname is not in the DNS Database then a blank string is returned.

Notes

IPv6 support is only available in Windows Vista or later.

Examples

ip = NetDNSLookup('capesoft.com',NetIPv6)

See Also

NetAddressLookup .

NetEncryptString(*string pInData, long pDataLength, String pPassword, long pAlgorithm=NET:CALG_AES_256, long pHashAlgorithm=NET:CALG_SHA_256, Long pCipherMode=NET:CRYPT_MODE_CBC, Long pPadding=NET:PKCS5_PADDING,<String pIV>,<*Long pLength>,<*String pTag>)

Description

This function encrypts a string, using a password, and returns the encrypted string. The original string is not altered. Note that storing encrypted data in CSTRINGs is not allowed because encrypted strings can contain the null (chr(0) character, which truncates data in CSTRINGs.

The encrypted string size will always be the same as, or larger than, the plain string size. The size growth will depend on the algorithm used. For AES this will be at the next multiple of 16 bytes.

Parameters

Parameter	Description
pInData	A pointer to the data to be encrypted. The original data is not altered.
pDataLength	The length of the data to encrypt.
pPassword	The password to use for the encryption. This field is not clipped. If pHashAlgorith is set to net:CALG_NOHASH then the password must be the correct length for the encryption algorithm. For AES256 this is 32 bytes.
pAlgorithmn	The Algorithm to use. Currently supported algorithms are; NET:CALG_AES_256
pHashAlgorithm	The Hashing Algorithm to use on the Password, before the encryption happens. Hashing a password improves the strength of the password. Algorithms supported by NetMakeHash are supported here.
pCipherMode	The cipher mode to use. Currently supported options are; NET:CRYPT_MODE_CBC, NET:CRYPT_MODE_GCM If you are using NET:CRYPT_MODE_GCM then you MUST pass the pTag parameter and you MUST store this. (See pTag parameter for more information.)
pPadding	The Padding mode to use. Currently supported options are; NET:PKCS5_PADDING
pIV	The Initialization Vector to use. The length of the Init Vector is determined by the algorithm. For AES 256 it's 16 bytes long. Strings that are two long are clipped. Strings that are too short are padded with chr(0). If not passed (or passed as a blank string) then a string of null characters (chr(0)) is used.
pLength	Contains the length of the binary data being passed back. The encrypted string size will always be the same as, or larger than, the plain string size. Since the exact size needs to be known (as a string of the exact size has to be passed to NetDecryptString or NetDecryptStringAES)
pTag	When using the cipher mode NET:CRYPT_MODE_GCM, a tag value (String 16) will be set for you. This string is passes as the pTag parameter. The function will populate this string with the new value.  The tag is not a secret, but needs to be stored (presumably, but not necessarily) along with the encrypted data. It is then passed to the NetDecryptString function when the data is decrypted. Failure to do this means the decryption will fail. This string is a binary string, and may contain the null character, and it is passed by reference, so a CSTRING is not allowed - it must be a STRING field.

Return Value

Returns the encrypted string. If the function fails a blank string is returned.

Notes

Strategies for managing the encrypted string length

When encrypting a string the length of the encrypted value may be longer than the original string (up to another blocksize-1 longer). when decrypting the string the exact correct length of encrypted data should be passed to the decrypting function. Unfortunately Clarion does not have a native string type that can contain both binary data, and has a determined length. Using a CSTRING is not possible (cannot contain binary data) and using CLIP on a STRING is not correct since the binary encrypted data could end in a space.

Using StringTheory

In code this can be handled using a StringTheory object;

str.SetValue(NetEncryptStringAES('some text to keep a secret', 'password'))

This can then be base64 encoded before being written to the disk

str.base64encode(st:nowrap)
cus:secret = str.GetValue()

Reversing this is straightforward;

str.SetValue(clip(cus:secret)) ! can clip, because base64 encoded.
str.base64decode()
str.SetValue(NetDecryptStringAES(str.GetValue(),'password')

One advantage of this approach is that the data is stored in the database as ASCII text, not binary, and will also travel well when exported to CSV, JSON, XML and so on. The primary disadvantage of this approach is that base64 uses up a bit more string space (25% more).

Using a Length Field

An alternative approach makes use of a Length field which works in conjunction with the String field.

cus:secret = NetEncryptStringAES('some text to keep a secret', 'password',cus:SecretLen)

Decrypt as

dec = NetDecryptStringAES(Sub(cus:secret,1,cus:SecretLen),'password'

If this approach is used then the database field type MUST be capable of holding binary data.

Using CLIP

dec = NetDecryptStringAES(clip(cus:secret),'password')

Ordinarily this approach would fail if the encrypted secret ended with one or more spaces. However, from NetTalk 12.02 this code will work but only for NetDecryptStringAES, not for NetDescryptString.


Examples

str  string(100)
enc  string(112)
  code
  str = 'NetTalk is Amazing'
  enc = NetEncryptString(str,len(str),'1234')

st  StringTheory
  code
  st.SetValue('NetTalk Is Amazing')
  enc = NetEncryptString(st.GetValuePtr(),st.Length(),'1234')

See Also

NetEncryptStringAES, NetDecryptString, NetDecryptStringAES

NetEncryptStringAES(String pInData, String pPassword, <*Long pLength>)

Description

Same as calling NetEncryptString, with all optional parameters set to default, and the Algorithm set to NET:CALG_AES_256.

Parameters

Parameter	Description
pInData	The data to encrypt.
pPassword	The password

Return Value

Returns the encrypted string. If the function fails a blank string is returned.

Examples

enc = NetEncryptStringAES('NetTalk is Amazing','1234')

See Also

NetEncryptString, NetDecryptString, NetDecryptStringAES

NetGenerateVapidKeys(*String pPrivate, *Long pPrivateLen, *String pPublic, *Long pPublicLen)

Description

This function generates a new VAPID public and private key pair.

Parameters

Parameter	Description
pPrivate	A string field, big enough for the Private Key
pPrivateLen	A long, which will be returned with the length of the Private Key
pPublic	A string field, big enough for the Public Key
pPublicLen	A long, which will be returned with the length of the Public Key

Return Value

All four parameters are populated by the function. If the function succeeds it returns net:ok, if it fails it returns net:notok. If it fails debug information is written to debugview.

The key strings contain binary values, and typically need to be converted to text for the template settings.

Example

PrivateKey           STRING(4096)                          
PublicKey         STRING(4096)                         
PrivateKeyLen        LONG                                  
PublicKeyLen         LONG                                  

  code
  result = NetGenerateVapidKeys(PrivateKey, PrivateKeyLen,PublicKey,PublicKeyLen)
 

See Also

NetGetIPInfo (*Net:IpInfoQType pQueue, long pShortList, long pFamily=Net:IPvAuto)

Description

Every computer has multiple IP addresses. This function populates a queue with information about each of the addresses currently assigned to this computer. This function best answers the question "What is the IP address of this machine on the LAN?"

Note that if your computer connects to a server on the WAN (like the internet) and goes through a NAT Router to get there, then that machine will see the IP address of the NAT router, and not any of the addresses in this queue. If you want to know what your IP address is as seen by external servers, then use a WebClient class to access a service like https://api.ipify.org .

Parameters

Parameter	Description
pQueue	A queue to contain the results of the call. The queue is of type Net:IpInfoQType. This type is declared in \clarion\accessory\libsrc\win\netall.inc Net:IpInfoQType   Queue, Type IPAddressCstr       cstring (NET:IPStringSize+1) SubnetMaskCstr      cstring (NET:IPStringSize+1) BroadCastCstr       cstring (NET:IPStringSize+1) Gateway1CStr        cstring (NET:IPStringSize+1) Gateway2CStr        cstring (NET:IPStringSize+1) Gateway3CStr        cstring (NET:IPStringSize+1) Gateway4CStr        cstring (NET:IPStringSize+1) Gateway5CStr        cstring (NET:IPStringSize+1) DHCPServerCStr      cstring (NET:IPStringSize+1) PrimaryWinsCstr     cstring (NET:IPStringSize+1) SecondaryWinsCStr   cstring (NET:IPStringSize+1) DCHPenabled         long WinsEnabled         long LeaseObtained       long LeaseExpires        long AdapterDescription  cstring (128+4) AdapterName         cstring (256+4) AdapterType         long AdapterIndex        long IPindex             long MACAddress          string(20) Family              Long                   End
pShortList	Deprecated: Set it to False. If this property is true then only IP, SubnetMast and BroadCast addresses are filled into the queue.
pFamily	If set to Net:IPvAuto then both IPv4 and IPv6 addresses are returned. If set to Net:IPv4 or Net:IPv6 then only those addresses are returned.

Return Value

Returns 0 if the function is successful, non zero otherwise.

Examples

qIP          QUEUE(Net:IpInfoQType),PRE()
             END
  Code
  NetGetIPInfo (qIP, 0) ! Get Full List

See also

NetOptions, NetGetIpNetTable .

NetGetIpNetTable (*Net:NetInfoQType pQueue, <String pMacAddress>, long pFamily=NET:AF_UNSPEC, Long pAdapter=0, long pFlags=0)

Description

In order to determine the IP address of another device on the network, based on its MAC address, a protocol known as the Address Resolution Protocol (ARP) exists. This is the protocol leveraged by the ARP command line program. It is also the protocol behind the Windows GetIpNetTable2 command.

NetTalk provides this utility function which wraps the GetIpNetTable2 Windows API call. It allows you to list all the devices on the network (with their IP addresses, and MAC addresses) or retrieve the IP address(es) associated with a specific MAC address.

By default this function will return both IPv4 and IPv6 addresses, but it can be set to limit this Family if desired.

Parameters

Parameter	Description
pQueue	A queue to contain the results of the call. The queue is of type Net:NetInfoQType. This type is declared in \clarion\accessory\libsrc\win\netall.inc Net:NetInfoQType           Queue, Type IPAddressCstr                cstring (NET:IPStringSize+1) MACAddress                   String(20) Family                       Long          ! = NET:AF_INET for IPv4 or NET:AF_INET6 for IPv6 AdapterIndex                 long State                        long   StateText                    string(20)   IsRouter                     Byte IsUnreachable                Byte                            End
pMacAddress	Pass a specific MAC address here (in the form aa-aa-aa-aa-aa-aa) and the returned queue will be filtered on that address. In other words only entries that match that address will be in the returned queue.
pFamily	This should be one of NET:AF_UNSPEC (0) for both IPv4 and IPv6 entries, NET:AF_INET (2) for only IPv4 entries or NET:AF_INET6 (23) for only IPv6 entries.
pAdapter	Use this option to limit the list to a specific NetWork adapter.

Return Value

Returns 0 if the function is successful, non zero otherwise.

Examples

qArp   Queue(Net:NetInfoQType)
       End
  Code
  result = NetGetIpNetTable(qArp)


  result = NetGetIpNetTable(qArp, , NET:AF_INET)

 
See also

NetOptions, NetGetIPInfo .

NetMakeHash (*string pInData, long pLength, long pHashType)
NetMakeHash (string pInData, long pHashType=net:CALG_SHA_256)

Description

Calculates the HASH value of a string.

Parameters

Parameter	Description
pInData	The string to Hash.
pLength	The length of the incoming string.
pHashType	One of the following; net:CALG_NOHASH net:CALG_MD2 net:CALG_MD4 net:CALG_MD5 net:CALG_SHA1 net:CALG_SHA_256 net:CALG_SHA_384 net:CALG_SHA_512

Return Value

Returns the hash of the string as a binary string value. If you need to convert this to Base64 or HexEncoding then use StringTheory to do that.

Examples

Hash a value in a simple string

str  String(10)
hash  String(1024)
  code
  str = 'abcde'
  hash = NetMakeHash(str,5,net:CALG_SHA_256)

Hash a value in a StringTheory object

str   StringTheory
  code
  str.SetValue('abcde')
  str.SetValue(NetMakeHash(str.GetValuePtr(),str.Length(),net:CALG_SHA_256))
  str.ToHex(st:UPPER)


See also

NetMakeHMAC

NetMakeHMAC (*String pInData, Long pLength, String pSecret, Long pHashType)

Description

Calculates the HMAC value of a string and secret pair.

Parameters

Parameter	Description
pInData	The string to Hash.
pLength	The length of the incoming string.
pSecret	The secret value used in the HMAC. This value will be clipped so cannot end with a space character.
pHashType	One of the following; net:CALG_MD5 net:CALG_SHA1 net:CALG_SHA_256 net:CALG_SHA_384 net:CALG_SHA_512

Return Value

Returns the HMAC of the string and secret as a binary string value. If you need to convert this to Base64 or HexEncoding then use StringTheory to do that.

Examples

HMAC a value in a simple string

str     String(10)
secret  string(10)
hmac    String(1024)
  code
  str = 'abcde'
  secret = '1234'
  hmac = NetMakeHMAC(str,5,secret,net:CALG_SHA_256)

HMAC a value in a StringTheory object

str     StringTheory
secret  string(10)
  code
  str.SetValue('abcde')
  secret = '1234'
  str.SetValue(NetMakeHMAC(str.GetValuePtr(),str.Length(),secret,net:CALG_SHA_256))
  str.ToHex(st:UPPER)


See also

NetMakeHash

NetOptions (long flag, *string pData)

Description

NetOptions is a general purpose function which lets you read, and write, various internal NetTalk settings.

Parameters

Parameter	Description
flag	One of the equates listed in the table below
pData	The value to set (when using SET equates) or the result from the function if using GET equates.

Equates

The where column below indicates where the call should be made.
After (You can only call this after the parent call in the Init() method),
Before (You can only call this before the parent call in the Init() method) or
Either (You can call this anytime you like)

Equate	Description	Where
NET:COUNTOUTGOINGPACKETS	Used by NetSimple objects to determine the number of outgoing packets that are still in the DLL. Used in the GetInfo() method.	After
NET:DNSLOOKUP	Does a DNS lookup on the string that you pass to it. The result is placed in the string. This is a blocking call. In other words processing is suspended while the DNS lookup occurs.	After
NET:SETENCRYPTIONKEY	Can be used to set a unique encryption key string for your applications. String passed should be of type string (24). Preferably set this early in the loading cycle before packets are sent or received.	Before
NET:GETDGINSTANCE	Gets the datagram instance of your NetAuto instance (starts at 0)	After
NET:GETDGPORT	Gets the datagram port number (see also NET:GETSPORT)	Either
NET:SETDGPORT	Sets the datagram port number (see also NET:SETSPORT)	Before
NET:GETDLLTHREAD	Gets the thread number of the NetTalk Callback Window, which is in the DLL. If the window is not open then this returns 0.	Either
NET:GETDLLVERSION	Gets the version out of the DLL being used. If you compile in local mode this will be the version of the .lib file that you compiled with, otherwise it will report the DLL version (standalone build).	After
NET:GETDNSLIST	Gets a comma separated list of the DNS Servers in specified in the Networking TCP/IP properties.	After
NET:GETHOSTNAME	Gets the hostname of the machine you are using	Either
NET:GETHOSTIPLIST	Gets a list of IP addresses for this machine.	Either
NET:GETIAMASERVICE	Tells NetTalk this process is a Service, and that it should not close down when the current Session Logs Off	Either
NET:GETINACTIVESERVICETIMER	(Advanced option). Gets the time to wait between polls to inactive servers. (in hs) - This only affects the NetAuto objects.	Either
NET:SETINACTIVESERVICETIMER	(Advanced option). Sets the time to wait between polls to inactive servers. (in hs) - This only affects the NetAuto objects.	Before
NET:GETMAXINSTANCES	Gets the maximum number of NetAuto instances that you can run on one machine.	Either
NET:SETMAXINSTANCES	Sets the maximum number of NetAuto instances that you can run on one machine.	Before
NET:GETNETDESCRIPTION	Gets the NetName Description of the current instance. This is the user friendly version of the netname e.g. 'Fred Bloggs at CapeSoft'	After
NET:SETNETDESCRIPTION	Sets the NetName Description of the current instance. This is the user friendly version of the netname e.g. 'Fred Bloggs at CapeSoft'	Before
NET:SETNETDESCRIPTION_ALWAYS	Sets the NetName description of the current instance. This is the user friendly version of the netname e.g. 'Fred Bloggs at CapeSoft'. This option also stores it in the registry for the next time as well.	Before
NET:GETNETID	Gets the NetID structure for the current instance. Net:AutoIDType is defined in \clarion\accessory\libsrc\win\netall.inc	After
NET:SETNETNAME	Sets the NetName of your NetAuto Instance	Before
NET:GETNETNAME	Gets the NetName of you NetAuto Instance. You can also call the NetAutoGetNetName() function.	After
NET:SETNETAUTOLISTENINGPORTIP	Allows you to bind the NetAuto Objects Listening Ports to a specific IP address. This can be useful if you are running multiple network cards, but would only be used in rare situations	Before
NET:SETRECOVERYOPTIONS	Sets the NetAuto objects Error Recovery parameters. Demonstrated in the netdemo application. Use the NET:AutoRecoveryOptionsType group.	Either
NET:GETRESEND_CloseConnectionBeforeResend	(Advanced option only). Indicates if the NetAuto objects' connection will be closed before any error correction resending takes place	Either
NET:SETRESEND_CloseConnectionBeforeResend	(Advanced option only). Sets if the NetAuto objects' connection must be closed before any error correction resending takes place.	Either
NET:GETRESEND_OnlySendIfHostActive	(Advanced option only). Indicates if the NetAuto objects' error correction resending takes place only if the Host is active in the Servers queue (ie that there is DG communication between server and client)	Either
NET:SETRESEND_OnlySendIfHostActive	(Advanced option only). Sets the NetAuto objects' error correction resending to take place only if the Host is active in the Servers queue (ie that there is DG communication between server and client)	Either
NET:GETSINSTANCE	Gets the streamed socket instance of your NetAuto instance (starts at 0)	After
NET:GETSPORT	Gets the streamed port number (see also NET:GETDGPORT)	Either
NET:SETSPORT	Sets the streamed port number (see also NET:SETDGPORT)	Before
NET:GETSTATS	Get Statistics on how many records are in queues and memory used	After
NET:SETUSEONE255BROADCAST	Tells the NetAuto Broadcast system to use one 255.255.255.255 broadcast instead of one broadcast per subnet. (Not recommended unless you know what you are doing).	Either
NET:GETOUTWAITING	Gets the size of data (in bytes) currently waiting in the qAutoOutgoingPacketsData	After

Return Value

The value returns nothing, although the contents of the pData parameter may be changed

Examples

1. Change the base DG port for your system

val   string(20)
 
  val = 27000
  NetOptions(NET:SETDGPORT,val)

2. Change the maximum number of instances of your program (or programs sharing the same Base DG Port) on the same machine.

val   string(20)
 
  val = 10
  NetOptions(NET:NET:SETMAXINSTANCES,val)


3. Use the Stats functionality to tell you how many outgoing NetSimple and NetAuto packets are waiting in the DLL.

SimpleOutData_Size long ! How many outgoing NetSimple packets in DLL
OutgoingPacketsData_Size long ! How many outgoing NetAuto packets in DLL

ourNETStats Group(NET:StatsType).
ourNETSTatsStr String (size(NET:StatsType)),over(ourNETStats)

GetStats Routine
  NetOptions (NET:GETSTATS, ourNetStatsStr) ! Call the DLL and ask for the stats
  SimpleOutData_Size = ourNetStats.qSimpleOutData_Size
  OutgoingPacketsData_Size = ourNetStats.qOutgoingPacketsData_Size

For a complete description of the Net:StatsType group look in \clarion\accessory\libsrc\win\netall.inc.


See also

NetPing (String pIP, long pTTL)

Description

Sends a PING to the destination address. Note this is a blocking, syncronous call. The result is returned immediately. Ping only checks to see if the server at the address will respond to a Ping command. It does not check if a port on the machine is open or not. Note that a Ping can fail even if the server is available as many servers are set up to reject Ping packets and not respond to them.

Therefore a successful Ping tells you (only) that a machine exists - it does not tell you if a port is open.
Also a failed Ping does not mean the server is unavailable, only that it has not replied to the Ping.

Parameters

Parameter	Description
pIP	The IP address to ping.
pTTL	Timeout (in milliseconds. 1000=1 second)

Return Value

Returns either 0 for success or ERROR:PingUnSuccessful if it fails.

Examples

result = NetPing('www.google.com',3000)