CapeSoft Logo

CapeSoft NetTalk
Utility Functions

Download Latest Version
Installed Version Latest Version

NetTalk Utility Functions

These functions are exposed by the NetTalk DLL and can be called "as is" without instantiating a class.

NetAddressLookup

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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)


[End of this document]
Return to NetTalk Documentation Index