EzRand Class

Properties   Methods   Events   Config Settings   Errors  

The EzRand class can be used to generate random numbers or bytes using a variety of algorithms.

Syntax

EzRand

Remarks

The EzRand class can be used to generate random numbers or bytes using a variety of algorithms and implementations.

To begin first set the Algorithm property to the desired value. This property specifies the algorithm and implementation that will be used to generate the number or bytes. Possible choices include ISAAC, the Microsoft Crypto API, and platform specific random and secure random implementations.

Next set Min and Max to define the acceptable range of values when generating an integer. The Seed property may optionally be set. Then simply call GetNextInt to generate a random number. the RandInt property will be populated with the generated value.

To generate a random set of bytes set RandBytesLength to the desired number of bytes and call GetNextBytes.

Property List

The following is the full list of the properties of the class with short descriptions. Click on the links for further details.

Method List

The following is the full list of the methods of the class with short descriptions. Click on the links for further details.

Event List

The following is the full list of the events fired by the class with short descriptions. Click on the links for further details.

Config Settings

The following is a list of config settings for the class with short descriptions. Click on the links for further details.

Algorithm Property (EzRand Class)

The random number algorithm.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetAlgorithm();
int SetAlgorithm(int iAlgorithm);

Unicode (Windows)
INT GetAlgorithm();
INT SetAlgorithm(INT iAlgorithm);

RA_ISAAC(0), 
RA_MSCRYPTO_API(1), 
RA_PLATFORM(2), 
RA_SECURE_PLATFORM(3), 
RA_RC4RANDOM(4)

int ipworksencrypt_ezrand_getalgorithm(void* lpObj);
int ipworksencrypt_ezrand_setalgorithm(void* lpObj, int iAlgorithm);

int GetAlgorithm();
int SetAlgorithm(int iAlgorithm);

Default Value

0

Remarks

This property specifies the algorithm used to generate the random number or bytes. Possible values are:

Data Type

Integer

Max Property (EzRand Class)

The exclusive upper bound.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetMax();
int SetMax(int iMax);

Unicode (Windows)
INT GetMax();
INT SetMax(INT iMax);

int ipworksencrypt_ezrand_getmax(void* lpObj);
int ipworksencrypt_ezrand_setmax(void* lpObj, int iMax);

int GetMax();
int SetMax(int iMax);

Default Value

100

Remarks

This property specifies the exclusive upper bound of the random integer to be generated. The value must be greater than Min. The default value is 100.

Data Type

Integer

Min Property (EzRand Class)

The inclusive lower bound.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetMin();
int SetMin(int iMin);

Unicode (Windows)
INT GetMin();
INT SetMin(INT iMin);

int ipworksencrypt_ezrand_getmin(void* lpObj);
int ipworksencrypt_ezrand_setmin(void* lpObj, int iMin);

int GetMin();
int SetMin(int iMin);

Default Value

0

Remarks

This property specifies the inclusive lower bound of the random integer to be generated. The value must be less than Max, and must not be negative. The default value is 0.

Data Type

Integer

RandBytes Property (EzRand Class)

The random byte array.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetRandBytes(char* &lpRandBytes, int &lenRandBytes);

Unicode (Windows)
INT GetRandBytes(LPSTR &lpRandBytes, INT &lenRandBytes);

int ipworksencrypt_ezrand_getrandbytes(void* lpObj, char** lpRandBytes, int* lenRandBytes);

QByteArray GetRandBytes();

Default Value

""

Remarks

This property holds the random byte array generated by calling GetNextBytes.

This property is read-only.

Data Type

Binary String

RandBytesLength Property (EzRand Class)

The length of the byte array to be generated.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetRandBytesLength();
int SetRandBytesLength(int iRandBytesLength);

Unicode (Windows)
INT GetRandBytesLength();
INT SetRandBytesLength(INT iRandBytesLength);

int ipworksencrypt_ezrand_getrandbyteslength(void* lpObj);
int ipworksencrypt_ezrand_setrandbyteslength(void* lpObj, int iRandBytesLength);

int GetRandBytesLength();
int SetRandBytesLength(int iRandBytesLength);

Default Value

16

Remarks

This property specifies the length of the random byte array to be generated. The RandBytes property will hold the byte array after GetNextBytes is called. The default value is 16.

Data Type

Integer

RandInt Property (EzRand Class)

The random integer.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetRandInt();

Unicode (Windows)
INT GetRandInt();

int ipworksencrypt_ezrand_getrandint(void* lpObj);

int GetRandInt();

Default Value

0

Remarks

This property holds the random integer generated by calling GetNextInt.

This property is read-only.

Data Type

Integer

Seed Property (EzRand Class)

The seed.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetSeed(char* &lpSeed, int &lenSeed);
int SetSeed(const char* lpSeed, int lenSeed);

Unicode (Windows)
INT GetSeed(LPSTR &lpSeed, INT &lenSeed);
INT SetSeed(LPCSTR lpSeed, INT lenSeed);

int ipworksencrypt_ezrand_getseed(void* lpObj, char** lpSeed, int* lenSeed);
int ipworksencrypt_ezrand_setseed(void* lpObj, const char* lpSeed, int lenSeed);

QByteArray GetSeed();
int SetSeed(QByteArray qbaSeed);

Default Value

""

Remarks

This property specifies the seed. This value is optional. If not specified and a seed is required the class will use the current time.

Seed Notes

• When Algorithm is set to 0 (raISAAC) the class uses the leftmost 256 bytes.
• When Algorithm is set to 1 (raMSCryptoAPI) the seed is ignored.
• When Algorithm is set to 2 (raPlatform) the class uses the leftmost 4 bytes.
• When Algorithm is set to 3 (raSecurePlatform) in .NET the seed is ignored. The seed is applicable in Java.

Data Type

Binary String

Config Method (EzRand Class)

Sets or retrieves a configuration setting.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* Config(const char* lpszConfigurationString);

Unicode (Windows)
LPWSTR Config(LPCWSTR lpszConfigurationString);

char* ipworksencrypt_ezrand_config(void* lpObj, const char* lpszConfigurationString);

QString Config(const QString& qsConfigurationString);

Remarks

Config is a generic method available in every class. It is used to set and retrieve configuration settings for the class.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

Error Handling (C++)

This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

GetNextBytes Method (EzRand Class)

Generates a sequence of random bytes.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetNextBytes();

Unicode (Windows)
INT GetNextBytes();

int ipworksencrypt_ezrand_getnextbytes(void* lpObj);

int GetNextBytes();

Remarks

This method generates a new sequence of random bytes. The RandBytesLength property specifies the length of the byte array. After calling this method the RandBytes will hold the random bytes. The following properties are applicable when calling this method:

• Algorithm
• RandBytesLength
• Seed

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

GetNextInt Method (EzRand Class)

Generates a random integer.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetNextInt();

Unicode (Windows)
INT GetNextInt();

int ipworksencrypt_ezrand_getnextint(void* lpObj);

int GetNextInt();

Remarks

This method generates a random integer. The Min and Max properties define the minimum and maximum values. After calling this method the RandInt property will hold the integer. The following properties are applicable when calling this method:

• Algorithm
• Min
• Max
• Seed

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Reset Method (EzRand Class)

Resets the class.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Reset();

Unicode (Windows)
INT Reset();

int ipworksencrypt_ezrand_reset(void* lpObj);

int Reset();

Remarks

When called, the class will reset all of its properties to their default values.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Error Event (EzRand Class)

Fired when information is available about errors during data delivery.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireError(EzRandErrorEventParams *e);

typedef struct {
  int ErrorCode;
  const char *Description;
  int reserved;
} EzRandErrorEventParams;


Unicode (Windows)
virtual INT FireError(EzRandErrorEventParams *e);

typedef struct {
  INT ErrorCode;
  LPCWSTR Description;
  INT reserved;
} EzRandErrorEventParams;

#define EID_EZRAND_ERROR 1

virtual INT IPWORKSENCRYPT_CALL FireError(INT &iErrorCode, LPSTR &lpszDescription);

class EzRandErrorEventParams {
public:
  int ErrorCode();

  const QString &Description();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void Error(EzRandErrorEventParams *e);

// Or, subclass EzRand and override this emitter function.
virtual int FireError(EzRandErrorEventParams *e) {...}

Remarks

The Error event is fired in case of exceptional conditions during message processing. Normally the class fails with an error.

The ErrorCode parameter contains an error code, and the Description parameter contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

Config Settings (EzRand Class)

EzRand Config Settings

Base Config Settings

Trappable Errors (EzRand Class)

Error Handling (C++)

Call the GetLastErrorCode() method to obtain the last called method's result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. Known error codes are listed below. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

EzRand Errors