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
pInDataA pointer to the data to be decrypted. The original data is not altered.
pDataLengthThe length of the data to decrypt.
pPasswordThe password to use for the decryption.
pAlgorithmnThe Algorithm to use. Currently supported algorithms are;
NET:CALG_AES_256
pHashAlgorithmThe 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.
pCipherModeThe cipher mode to use. Currently supported options are;
NET:CRYPT_MODE_CBC
pPaddingThe Padding mode to use. Currently supported options are;
NET:PKCS5_PADDING
pIVThe 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'))



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
pInDataThe data to decrypt.
pPasswordThe password

Return Value


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

Examples

dec = NetDecryptStringAES(someencrypteddata,'1234')


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

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
pInDataA pointer to the data to be encrypted. The original data is not altered.
pDataLengthThe length of the data to encrypt.
pPasswordThe password to use for the encryption.
pAlgorithmnThe Algorithm to use. Currently supported algorithms are;
NET:CALG_AES_256
pHashAlgorithmThe 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.
pCipherModeThe cipher mode to use. Currently supported options are;
NET:CRYPT_MODE_CBC
pPaddingThe Padding mode to use. Currently supported options are;
NET:PKCS5_PADDING
pIVThe Initialization Vector to use. This parameter is not yet supported.

Return Value


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

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



NetEncryptStringAES

NetEncryptStringAES(String pInData, String pPassword)

Description

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

Parameters

Parameter Description
pInDataThe data to encrypt.
pPasswordThe password

Return Value


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

Examples

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


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

pShortListDeprecated: 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
pInDataThe string to Hash.
pLengthThe length of the incoming string.
pHashTypeOne 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
pInDataThe string to Hash.
pLengthThe length of the incoming string.
pSecretThe secret value used in the HMAC. This value will be clipped so cannot end with a space character.
pHashTypeOne 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
flagOne of the equates listed in the table below
pDataThe 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:COUNTOUTGOINGPACKETSUsed by NetSimple objects to determine the number of outgoing packets that are still in the DLL. Used in the GetInfo() method.After
NET:DNSLOOKUPDoes 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:SETENCRYPTIONKEYCan 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:GETDGINSTANCEGets the datagram instance of your NetAuto instance (starts at 0)After
NET:GETDGPORTGets the datagram port number (see also NET:GETSPORT) Either
NET:SETDGPORTSets the datagram port number (see also NET:SETSPORT) Before
NET:GETDLLTHREADGets 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:GETDLLVERSIONGets 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:GETDNSLISTGets a comma separated list of the DNS Servers in specified in the Networking TCP/IP properties.After
NET:GETHOSTNAMEGets the hostname of the machine you are usingEither
NET:GETHOSTIPLISTGets a list of IP addresses for this machine.Either
NET:GETIAMASERVICETells NetTalk this process is a Service, and that it should not close down when the current Session Logs OffEither
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:GETMAXINSTANCESGets the maximum number of NetAuto instances that you can run on one machine. Either
NET:SETMAXINSTANCESSets the maximum number of NetAuto instances that you can run on one machine. Before
NET:GETNETDESCRIPTIONGets the NetName Description of the current instance. This is the user friendly version of the netname e.g. 'Fred Bloggs at CapeSoft'After
NET:SETNETDESCRIPTIONSets 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_ALWAYSSets 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:GETNETIDGets the NetID structure for the current instance. Net:AutoIDType is defined in \clarion\accessory\libsrc\win\netall.inc After
NET:SETNETNAMESets the NetName of your NetAuto InstanceBefore
NET:GETNETNAMEGets the NetName of you NetAuto Instance. You can also call the NetAutoGetNetName() function.After
NET:SETNETAUTOLISTENINGPORTIPAllows 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 situationsBefore
NET:SETRECOVERYOPTIONSSets 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:GETSINSTANCEGets the streamed socket instance of your NetAuto instance (starts at 0)After
NET:GETSPORTGets the streamed port number (see also NET:GETDGPORT) Either
NET:SETSPORTSets the streamed port number (see also NET:SETDGPORT) Before
NET:GETSTATSGet Statistics on how many records are in queues and memory usedAfter
NET:SETUSEONE255BROADCASTTells 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:GETOUTWAITINGGets 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
pIPThe IP address to ping.
pTTLTimeout (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