NewGamePhysics.Networking.PlayTrulyRandom Class Reference

Interface to the playtrulyrandom.com webservices. More...

List of all members.

Public Member Functions
	PlayTrulyRandom (string agentName)
	Creates an instance of the PlayTrulyRandom access object for an agent. A new username is created as GUID string. A retrieve pool of 256 bits is set.
	PlayTrulyRandom (string agentName, int retrievePoolSize)
	Creates an instance of the PlayTrulyRandom access object for an agent. A new username is created as GUID string.
	PlayTrulyRandom (string agentName, string userName)
	Creates an instance of the PlayTrulyRandom access object for an agent and the specific user. A retrieve pool of 256 bits is set.
	PlayTrulyRandom (string agentName, string userName, int retrievePoolSize)
	Creates an instance of the PlayTrulyRandom submittor for an agent.
void	OnlineSubmit (object param)
	Submits the bits to the online collection service. Updates error flag.
void	OnlineUsage (object param)
	Submits the usage data to the online collection service. Updates error flag.
void	RegisterAgent ()
	Register with the webservice. Syncronous call. May update error flag.
string	OnlineRetrieve (int numberOfBits)
	Retrieve bits from the online collection service. Updates error flag.
string	PoolRetrieve (int numberOfBits)
	Retrieve bits from internal bit pool filled by the online collection service. May make one or more calls to the online webservice.
int	Next (int minValue, int maxValue, out int retrievedBits)
	Generate random number within a given range [min,max] by retrieving bits from the webservice and mapping them into the range. This may require multiple pool or webservice requests.
Properties
string	LastMessage [get]
	Gets the last message from the last online call.
bool	Error [get]
	Gets the error flag from the last online call.

---

Detailed Description

Interface to the playtrulyrandom.com webservices.

Definition at line 18 of file PlayTrulyRandom.cs.

---

Constructor & Destructor Documentation

NewGamePhysics.Networking.PlayTrulyRandom.PlayTrulyRandom

(

string

agentName

)

Creates an instance of the PlayTrulyRandom access object for an agent. A new username is created as GUID string. A retrieve pool of 256 bits is set.

Parameters:

agentName

The agent name.

Definition at line 85 of file PlayTrulyRandom.cs.

            : this(agentName, Guid.NewGuid().ToString(), 256)
        {
        }

NewGamePhysics.Networking.PlayTrulyRandom.PlayTrulyRandom	(	string	agentName,
		int	retrievePoolSize
	)

Creates an instance of the PlayTrulyRandom access object for an agent. A new username is created as GUID string.

Parameters:

	agentName	The agent name.
	retrievePoolSize	The retrieve pool size. Must be in the range [8,1024].

Definition at line 99 of file PlayTrulyRandom.cs.

            : this(agentName, Guid.NewGuid().ToString(), retrievePoolSize)
        {
        }

NewGamePhysics.Networking.PlayTrulyRandom.PlayTrulyRandom	(	string	agentName,
		string	userName
	)

Creates an instance of the PlayTrulyRandom access object for an agent and the specific user. A retrieve pool of 256 bits is set.

Parameters:

	agentName	The agent name.
	userName	The user name.

Definition at line 110 of file PlayTrulyRandom.cs.

            : this(agentName, userName, 256)
        {
        }

NewGamePhysics.Networking.PlayTrulyRandom.PlayTrulyRandom	(	string	agentName,
		string	userName,
		int	retrievePoolSize
	)

Creates an instance of the PlayTrulyRandom submittor for an agent.

Parameters:

	agentName	The agent name.
	userName	The user name.
	retrievePoolSize	The retrieve pool size. Must be in the range [8,1024].

Definition at line 124 of file PlayTrulyRandom.cs.

        {
            // Check arguments
            if (string.IsNullOrEmpty(agentName))
            {
                throw new ArgumentNullException(
                    "agentName",
                    "Parameter cannot be null or empty.");
            }

            if (null == userName)
            {
                throw new ArgumentNullException("userName");
            }

            if ((retrievePoolSize < 2) || (retrievePoolSize > 1024))
            {
                throw new ArgumentOutOfRangeException(
                    "retrievePoolSize",
                    "Must be in the range [8,1024]");
            }
            // Store parameters
            this.agentName = Uri.EscapeDataString(agentName);
            this.userName = Uri.EscapeDataString(userName);
            this.retrievePoolSize = retrievePoolSize;

            string commonPart = "?source=" + agentName + "&user=" + userName + "&";

            // Build submission URL without bits data value:
            // Example: http://www.playtrulyrandom.com/submit.php?source=pendulumgame_v1&user=xyz&bits=011001
            this.submitUrl = baseUrl + "submit.php" + commonPart + "bits=";

            // Build retrieval URL without n data value:
            // Example: http://www.playtrulyrandom.com/retrieve.php?source=montygame_v1&user=xyz&n=32
            this.retrieveUrl = baseUrl + "retrieve.php" + commonPart + "n=";

            // Build usage URL without duration data value:
            // Example: http://www.playtrulyrandom.com/retrieve.php?source=montygame_v1&user=xyz&duration=32
            this.usageUrl = baseUrl + "usage.php" + commonPart + "duration=";

            // Reset retrieve pool state
            this.retrievePoolCache = string.Empty;
            this.retrievePoolPos = -1;
        }

---

Member Function Documentation

int NewGamePhysics.Networking.PlayTrulyRandom.Next	(	int	minValue,
		int	maxValue,
		out int	retrievedBits
	)

Generate random number within a given range [min,max] by retrieving bits from the webservice and mapping them into the range. This may require multiple pool or webservice requests.

Parameters:

	minValue	The inclusive minimum value to be generated.
	maxValue	The inclusive maximum value to be generated. maxValue must be greater or equals than minValue.
	retrievedBits	Number of bits retrieved to generate random number.

Returns:

A random number within the range.

Definition at line 369 of file PlayTrulyRandom.cs.

        {
            if (maxValue < minValue)
            {
                throw new ArgumentException(
                    "maxValue must be greater or equals than minValue",
                    "maxValue");
            }

            int result;
            retrievedBits = 0;

            // Assume min value
            result = minValue;

            // Determine difference plus one
            long delta = (long)maxValue - (long)minValue;
            if (delta < 1)
            {
                return result;
            }

            // Determine number of bits needed
            int numberOfBits = 1;
            long currentValue = 2;
            long deltaPlus = delta + 1;
            while (deltaPlus > currentValue)
            {
                numberOfBits++;
                currentValue *= 2;
            }

            // We MUST retrieve new bits until we have a number 
            // that is within the requested delta range
            // to ensure uniformity; a modulus calculation is
            // NOT appropriate here.
            long randomNumber = 0;
            do
            {
                // Get a bit string
                string randomBits = this.PoolRetrieve(numberOfBits);
                retrievedBits += numberOfBits;
                if (randomBits.Length != numberOfBits)
                {
                    this.lastMessage = String.Format(
                        "Could not retrieve the required number of bits. " +
                        "Expecting: {0} bits, " +
                        "Got: {1} bits.",
                        numberOfBits,
                        randomBits.Length);
                    this.error = true;
                    throw new ApplicationException(this.lastMessage);
                }

                // Convert to number
                randomNumber = Convert.ToInt64(randomBits, 2);
            } while (randomNumber > delta);

            // Calculate result
            result = (int)((long)minValue + randomNumber);

            return result;
        }

string NewGamePhysics.Networking.PlayTrulyRandom.OnlineRetrieve

(

int

numberOfBits

)

Retrieve bits from the online collection service. Updates error flag.

Parameters:

numberOfBits

The number of bits to read.

Returns:

A bit string consisting of 0 and 1 characters.

Definition at line 265 of file PlayTrulyRandom.cs.

        {
            // Check input parameters
            if ((numberOfBits < 1) || (numberOfBits > 1024))
            {
                throw new ArgumentOutOfRangeException(
                    "numberBits",
                    "Requested number must be between 1 and 1024");
            }

            // Reset error message
            this.lastMessage = string.Empty;
            this.error = false;

            // Create REST url
            Uri url = new Uri(this.retrieveUrl + Uri.EscapeDataString(numberOfBits.ToString()));

            // Submit query
            string result = UrlGet(url);

            // Result contains bits
            return result;
        }

void NewGamePhysics.Networking.PlayTrulyRandom.OnlineSubmit

(

object

param

)

Submits the bits to the online collection service. Updates error flag.

Parameters:

param

The string representation of a bit string consisting of 0 and 1's to submit.

Definition at line 193 of file PlayTrulyRandom.cs.

        {
            // The bits to submit
            string bitsToSumit = (string)param;

            // Reset error message
            this.lastMessage = string.Empty;
            this.error = false;

            // Check if we have to submit anything
            if (!String.IsNullOrEmpty(bitsToSumit))
            {
                // Create REST url
                Uri url = new Uri(this.submitUrl + Uri.EscapeDataString(bitsToSumit));

                // Submit query, ignore result
                string result = UrlGet(url);
            }
        }

void NewGamePhysics.Networking.PlayTrulyRandom.OnlineUsage

(

object

param

)

Submits the usage data to the online collection service. Updates error flag.

Parameters:

param

The integer representation number of seconds of usage to submit.

Definition at line 220 of file PlayTrulyRandom.cs.

        {
            // The seconds to submit
            int usageSeconds = (int)param;

            // Reset error message
            this.lastMessage = string.Empty;
            this.error = false;

            // Check if we have to submit anything
            if (usageSeconds > 0)
            {
                // Create REST url
                Uri url = new Uri(this.usageUrl + usageSeconds.ToString());

                // Submit query, ignore result
                string result = UrlGet(url);
            }
        }

string NewGamePhysics.Networking.PlayTrulyRandom.PoolRetrieve

(

int

numberOfBits

)

Retrieve bits from internal bit pool filled by the online collection service. May make one or more calls to the online webservice.

Parameters:

numberOfBits

The number of bits to read.

Returns:

A bit string consisting of 0 and 1 characters.

Definition at line 298 of file PlayTrulyRandom.cs.

        {
            // Reset result string
            string retrievedBits = string.Empty;

            // Loop to copy bits
            int bitsToCopy = numberOfBits;
            while (bitsToCopy > 0)
            {
                // Check if we need to fill the cache
                if ((this.retrievePoolPos < 0) || (this.retrievePoolPos == this.retrievePoolSize))
                {
                    // Fill the cache from online source
                    this.retrievePoolCache = this.OnlineRetrieve(this.retrievePoolSize);
                    this.retrievePoolPos = 0;

                    if (this.Error)
                    {
                        throw new Exception(
                            "Could not retrieve random data. " +
                            this.LastMessage);
                    }

                    if (this.retrievePoolCache.Length != this.retrievePoolSize)
                    {
                        throw new Exception(
                            "Could not retrieve the required number of bits. " +
                            "Expecting: " + this.retrievePoolSize + " bits, " +
                            "Got: " + this.retrievePoolCache.Length + " bits.");
                    }
                }

                // Now copy cached pool to output string
                int bitsLeftInPool = this.retrievePoolSize - this.retrievePoolPos;
                if (bitsLeftInPool >= bitsToCopy)
                {
                    // Have enough bits in cache, use them and update pos
                    retrievedBits += this.retrievePoolCache.Substring(this.retrievePoolPos, bitsToCopy);
                    this.retrievePoolPos += bitsToCopy;
                    bitsToCopy = 0;
                }
                else
                {
                    // Don't have enough bits in cache, use what we have
                    retrievedBits += this.retrievePoolCache.Substring(this.retrievePoolPos, bitsLeftInPool);
                    bitsToCopy -= bitsLeftInPool;

                    // Mark pos to load more
                    this.retrievePoolPos = -1;
                }
            }

            return retrievedBits;
        }

void NewGamePhysics.Networking.PlayTrulyRandom.RegisterAgent

(

)

Register with the webservice. Syncronous call. May update error flag.

Definition at line 244 of file PlayTrulyRandom.cs.

        {
            // Reset error message
            this.lastMessage = string.Empty;
            this.error = false;

            // Create REST url
            Uri url = new Uri(this.usageUrl + "1&hrngmode=1");

            // Submit query, ignore result
            string result = UrlGet(url);
        }

---

Property Documentation

bool NewGamePhysics.Networking.PlayTrulyRandom.Error [get]

Gets the error flag from the last online call.

Definition at line 181 of file PlayTrulyRandom.cs.

string NewGamePhysics.Networking.PlayTrulyRandom.LastMessage [get]

Gets the last message from the last online call.

Definition at line 173 of file PlayTrulyRandom.cs.

---

The documentation for this class was generated from the following file:

• C:/Users/Andreas Schiffler/Desktop/SVN/NewGamePhysics/NewGamePhysics/Networking/PlayTrulyRandom.cs