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

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

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.

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

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.

    00111             : this(agentName, userName, 256)
    00112         {
    00113         }

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.

    00125         {
    00126             // Check arguments
    00127             if (string.IsNullOrEmpty(agentName))
    00128             {
    00129                 throw new ArgumentNullException(
    00130                     "agentName",
    00131                     "Parameter cannot be null or empty.");
    00132             }
    00133
    00134             if (null == userName)
    00135             {
    00136                 throw new ArgumentNullException("userName");
    00137             }
    00138
    00139             if ((retrievePoolSize < 2) || (retrievePoolSize > 1024))
    00140             {
    00141                 throw new ArgumentOutOfRangeException(
    00142                     "retrievePoolSize",
    00143                     "Must be in the range [8,1024]");
    00144             }
    00145             // Store parameters
    00146             this.agentName = Uri.EscapeDataString(agentName);
    00147             this.userName = Uri.EscapeDataString(userName);
    00148             this.retrievePoolSize = retrievePoolSize;
    00149
    00150             string commonPart = "?source=" + agentName + "&user=" + userName + "&";
    00151
    00152             // Build submission URL without bits data value:
    00153             // Example: http://www.playtrulyrandom.com/submit.php?source=pendulumgame_v1&user=xyz&bits=011001
    00154             this.submitUrl = baseUrl + "submit.php" + commonPart + "bits=";
    00155
    00156             // Build retrieval URL without n data value:
    00157             // Example: http://www.playtrulyrandom.com/retrieve.php?source=montygame_v1&user=xyz&n=32
    00158             this.retrieveUrl = baseUrl + "retrieve.php" + commonPart + "n=";
    00159
    00160             // Build usage URL without duration data value:
    00161             // Example: http://www.playtrulyrandom.com/retrieve.php?source=montygame_v1&user=xyz&duration=32
    00162             this.usageUrl = baseUrl + "usage.php" + commonPart + "duration=";
    00163
    00164             // Reset retrieve pool state
    00165             this.retrievePoolCache = string.Empty;
    00166             this.retrievePoolPos = -1;
    00167         }

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

    00370         {
    00371             if (maxValue < minValue)
    00372             {
    00373                 throw new ArgumentException(
    00374                     "maxValue must be greater or equals than minValue",
    00375                     "maxValue");
    00376             }
    00377
    00378             int result;
    00379             retrievedBits = 0;
    00380
    00381             // Assume min value
    00382             result = minValue;
    00383
    00384             // Determine difference plus one
    00385             long delta = (long)maxValue - (long)minValue;
    00386             if (delta < 1)
    00387             {
    00388                 return result;
    00389             }
    00390
    00391             // Determine number of bits needed
    00392             int numberOfBits = 1;
    00393             long currentValue = 2;
    00394             long deltaPlus = delta + 1;
    00395             while (deltaPlus > currentValue)
    00396             {
    00397                 numberOfBits++;
    00398                 currentValue *= 2;
    00399             }
    00400
    00401             // We MUST retrieve new bits until we have a number
    00402             // that is within the requested delta range
    00403             // to ensure uniformity; a modulus calculation is
    00404             // NOT appropriate here.
    00405             long randomNumber = 0;
    00406             do
    00407             {
    00408                 // Get a bit string
    00409                 string randomBits = this.PoolRetrieve(numberOfBits);
    00410                 retrievedBits += numberOfBits;
    00411                 if (randomBits.Length != numberOfBits)
    00412                 {
    00413                     this.lastMessage = String.Format(
    00414                         "Could not retrieve the required number of bits. " +
    00415                         "Expecting: {0} bits, " +
    00416                         "Got: {1} bits.",
    00417                         numberOfBits,
    00418                         randomBits.Length);
    00419                     this.error = true;
    00420                     throw new ApplicationException(this.lastMessage);
    00421                 }
    00422
    00423                 // Convert to number
    00424                 randomNumber = Convert.ToInt64(randomBits, 2);
    00425             } while (randomNumber > delta);
    00426
    00427             // Calculate result
    00428             result = (int)((long)minValue + randomNumber);
    00429
    00430             return result;
    00431         }

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.

    00266         {
    00267             // Check input parameters
    00268             if ((numberOfBits < 1) || (numberOfBits > 1024))
    00269             {
    00270                 throw new ArgumentOutOfRangeException(
    00271                     "numberBits",
    00272                     "Requested number must be between 1 and 1024");
    00273             }
    00274
    00275             // Reset error message
    00276             this.lastMessage = string.Empty;
    00277             this.error = false;
    00278
    00279             // Create REST url
    00280             Uri url = new Uri(this.retrieveUrl + Uri.EscapeDataString(numberOfBits.ToString()));
    00281
    00282             // Submit query
    00283             string result = UrlGet(url);
    00284
    00285             // Result contains bits
    00286             return result;
    00287         }

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.

    00194         {
    00195             // The bits to submit
    00196             string bitsToSumit = (string)param;
    00197
    00198             // Reset error message
    00199             this.lastMessage = string.Empty;
    00200             this.error = false;
    00201
    00202             // Check if we have to submit anything
    00203             if (!String.IsNullOrEmpty(bitsToSumit))
    00204             {
    00205                 // Create REST url
    00206                 Uri url = new Uri(this.submitUrl + Uri.EscapeDataString(bitsToSumit));
    00207
    00208                 // Submit query, ignore result
    00209                 string result = UrlGet(url);
    00210             }
    00211         }

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.

    00221         {
    00222             // The seconds to submit
    00223             int usageSeconds = (int)param;
    00224
    00225             // Reset error message
    00226             this.lastMessage = string.Empty;
    00227             this.error = false;
    00228
    00229             // Check if we have to submit anything
    00230             if (usageSeconds > 0)
    00231             {
    00232                 // Create REST url
    00233                 Uri url = new Uri(this.usageUrl + usageSeconds.ToString());
    00234
    00235                 // Submit query, ignore result
    00236                 string result = UrlGet(url);
    00237             }
    00238         }

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.

    00299         {
    00300             // Reset result string
    00301             string retrievedBits = string.Empty;
    00302
    00303             // Loop to copy bits
    00304             int bitsToCopy = numberOfBits;
    00305             while (bitsToCopy > 0)
    00306             {
    00307                 // Check if we need to fill the cache
    00308                 if ((this.retrievePoolPos < 0) || (this.retrievePoolPos == this.retrievePoolSize))
    00309                 {
    00310                     // Fill the cache from online source
    00311                     this.retrievePoolCache = this.OnlineRetrieve(this.retrievePoolSize);
    00312                     this.retrievePoolPos = 0;
    00313
    00314                     if (this.Error)
    00315                     {
    00316                         throw new Exception(
    00317                             "Could not retrieve random data. " +
    00318                             this.LastMessage);
    00319                     }
    00320
    00321                     if (this.retrievePoolCache.Length != this.retrievePoolSize)
    00322                     {
    00323                         throw new Exception(
    00324                             "Could not retrieve the required number of bits. " +
    00325                             "Expecting: " + this.retrievePoolSize + " bits, " +
    00326                             "Got: " + this.retrievePoolCache.Length + " bits.");
    00327                     }
    00328                 }
    00329
    00330                 // Now copy cached pool to output string
    00331                 int bitsLeftInPool = this.retrievePoolSize - this.retrievePoolPos;
    00332                 if (bitsLeftInPool >= bitsToCopy)
    00333                 {
    00334                     // Have enough bits in cache, use them and update pos
    00335                     retrievedBits += this.retrievePoolCache.Substring(this.retrievePoolPos, bitsToCopy);
    00336                     this.retrievePoolPos += bitsToCopy;
    00337                     bitsToCopy = 0;
    00338                 }
    00339                 else
    00340                 {
    00341                     // Don't have enough bits in cache, use what we have
    00342                     retrievedBits += this.retrievePoolCache.Substring(this.retrievePoolPos, bitsLeftInPool);
    00343                     bitsToCopy -= bitsLeftInPool;
    00344
    00345                     // Mark pos to load more
    00346                     this.retrievePoolPos = -1;
    00347                 }
    00348             }
    00349
    00350             return retrievedBits;
    00351         }

void NewGamePhysics.Networking.PlayTrulyRandom.RegisterAgent | ( |  | ) |

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

Definition at line 244 of file PlayTrulyRandom.cs.

    00245         {
    00246             // Reset error message
    00247             this.lastMessage = string.Empty;
    00248             this.error = false;
    00249
    00250             // Create REST url
    00251             Uri url = new Uri(this.usageUrl + "1&hrngmode=1");
    00252
    00253             // Submit query, ignore result
    00254             string result = UrlGet(url);
    00255         }

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