CapeSoft.Com
Clarion Accessories
NetTalk
Doc Index
Utility Functions
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.

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.
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. This parameter is not yet supported.

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

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.
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. This parameter is not yet supported.
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

NetGetIPInfo

NetGetIPInfo (*Net:IpInfoQType pQueue, long pShortList)

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

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