Dice/PbP/RollPost - Revision history

Skizzerz: /* Methods */

2017-10-06T00:48:25Z

Methods

Skizzerz at 20:21, 9 May 2017

2017-05-09T20:21:53Z

Skizzerz: update serialization

2017-05-05T18:35:03Z

update serialization

Skizzerz: +example

2017-04-19T23:12:21Z

+example

Skizzerz: Created page with "{{APIdoc|RollPost Class}} Contains information about all of the rolls on a post, including basic anti-cheat detection. {{ns|PbP}} == Inheritance Hierarchy == System.Object :..."

2017-04-19T23:02:07Z

Created page with "{{APIdoc|RollPost Class}} Contains information about all of the rolls on a post, including basic anti-cheat detection. {{ns|PbP}} == Inheritance Hierarchy == System.Object :..."

New page

{{APIdoc|RollPost Class}}
Contains information about all of the rolls on a post, including basic anti-cheat detection.

{{ns|PbP}}

== Inheritance Hierarchy ==
System.Object
:Dice.PbP.RollPost

== Syntax ==
<syntaxhighlight lang="C#">
[Serializable]
public class RollPost : ISerializable, IDeserializationCallback
</syntaxhighlight>

== Constructors ==
{| class="wikitable"
! style="width: 5em" |
! Name !! Description
|-
| {{public}} {{method}} || [[/RollPost ()|RollPost()]] || Constructs a new, empty RollPost.
|-
| {{protected}} {{method}} || [[/RollPost (SerializationInfo, StreamingContext)|RollPost(SerializationInfo, StreamingContext)]] || Constructs a new RollPost using serialized data.
|}

== Methods ==
{| class="wikitable"
! style="width: 5em" |
! Name !! Description
|-
| {{public}} {{method}} || [[/AddRoll (String)|AddRoll(String)]] || Adds a new roll to the post using the DefaultConfig if the roll needs to be evaluated.
|-
| {{public}} {{method}} || [[/AddRoll (String, RollerConfig)|AddRoll(String, RollerConfig)]] || Adds a new roll to the post using the given config if the roll needs to be evaluated.
|-
| {{public}} {{method}} || [[/GetObjectData|GetObjectData(SerializationInfo, StreamingContext)]] || Serializes a RollPost.
|-
| {{public}} {{method}} || [[/OnDeserialization|OnDeserialization(Object)]] || Completes deserialization of the RollPost once the entire object graph has been deserialized.
|-
| {{private}} {{method}} || [[/PostMacros|PostMacros(MacroContext)]] || Executes PbP-specific macros, which are documented on in the [[Dice Reference#Play-by-Post Macros|dice reference]].
|-
| {{private}} {{method}} || [[/RollMacro|RollMacro(MacroContext, String[])]] || Contains the logic for the {{c|[roll]}} macro.
|-
| {{public}} {{method}} || [[/Validate|Validate()]] || Checks if Current has diverged from Pristine.
|}

== Properties ==
{| class="wikitable"
! style="width: 5em" |
! Name !! Description
|-
| {{public}} {{property}} || [[/Current|Current]] || Gets the current version of the post (the one being checked).
|-
| {{protected}} {{property}} || [[/CurrentList|CurrentList]] || Gets the mutable version of Current.
|-
| {{public}} {{property}} || [[/Pristine|Pristine]] || Gets the "pristine" version of the post.
|-
| {{protected}} {{property}} || [[/PristineList|PristineList]] || Gets the mutable version of Pristine.
|-
| {{public}} {{property}} || [[/Stored|Stored]] || Gets the most recent saved version of the post.
|-
| {{protected}} {{property}} || [[/StoredList|StoredList]] || Gets the mutable version of Stored.
|}

== Fields ==
{| class="wikitable"
! style="width: 5em" |
! Name !! Description
|-
| {{private}} {{field}} || [[/_current|_current]] || The current version of the post.
|-
| {{private}} {{field}} || [[/_diverged|_diverged]] || How many levels has Current diverged from Pristine at the moment.
|-
| {{private}} {{field}} || [[/_pristine|_pristine]] || The pristine version of the post.
|-
| {{private}} {{field}} || [[/_stored|_stored]] || The stored version of the post.
|}

== Remarks ==
When a new post is made, a new RollPost instance should be constructed and stored along with that post in the database (using BinaryFormatter to serialize it). The AddPost() method is used to add rolls to the post, and Validate() is used to determine if the post has been modified in a way that indicates cheating. Even if you do not care about the cheating detection, '''Validate() must be called before serializing a RollPost.''' If you do not do this, the Pristine version of the roll will not be updated, which can cause issues down the line for future edits causing expressions to be rerolled instead of taking on their prior values.

When processing an existing post, deserialize the stored RollPost, then call AddRoll() again for all rolls in the post. RollPost will re-use previously rolled values for those rolls if possible, otherwise it will reroll them. After all rolls have been added via AddRoll(), Validate() should be called to determine whether or not cheating happened and to update some internal state, and then you can iterate over Current to retrieve all of the individual [[Dice/RollResult|RollResults]].

@@ Line 36: / Line 36: @@
 |-
 | {{public}} {{method}} || [[/GetObjectData|GetObjectData(SerializationInfo, StreamingContext)]] || Serializes a RollPost. This method should not be directly called.
 |-
 | {{public}} {{method}} || [[/OnDeserialization|OnDeserialization(Object)]] || Completes deserialization of the RollPost once the entire object graph has been deserialized. This method should not be directly called.

@@ Line 11: / Line 11: @@
 <syntaxhighlight lang="C#">
 [Serializable]
-public class RollPost : ISerializable, IDeserializationCallback
+[DataContract]
 </syntaxhighlight>
@@ Line 33: / Line 34: @@
 | {{public}} {{method}} || [[/AddRoll (String, RollerConfig)|AddRoll(String, RollerConfig)]] || Adds a new roll to the post using the given config if the roll needs to be evaluated.
 |-
-| {{public}} {{method}} || [[/GetObjectData|GetObjectData(SerializationInfo, StreamingContext)]] || Serializes a RollPost.
+| {{public}} {{static}} {{method}} || [[/Deserialize|Deserialize(Stream)]] || Deserializes a serialized RollPost.
 |-
-| {{public}} {{method}} || [[/OnDeserialization|OnDeserialization(Object)]] || Completes deserialization of the RollPost once the entire object graph has been deserialized.
+| {{public}} {{method}} || [[/GetObjectData|GetObjectData(SerializationInfo, StreamingContext)]] || Serializes a RollPost. This method should not be directly called.
 |-
 | {{private}} {{method}} || [[/PostMacros|PostMacros(MacroContext)]] || Executes PbP-specific macros, which are documented on in the [[Dice Reference#Play-by-Post Macros|dice reference]].
 |-
 | {{private}} {{method}} || [[/RollMacro|RollMacro(MacroContext, String[])]] || Contains the logic for the {{c|[roll]}} macro.
 |-
 | {{public}} {{method}} || [[/Validate|Validate()]] || Checks if Current has diverged from Pristine.
@@ Line 52: / Line 57: @@
 |-
 | {{protected}} {{property}} || [[/CurrentList|CurrentList]] || Gets the mutable version of Current.
 |-
 | {{public}} {{property}} || [[/Pristine|Pristine]] || Gets the "pristine" version of the post.
@@ Line 77: / Line 86: @@
 == Remarks ==
-When a new post is made, a new RollPost instance should be constructed and stored along with that post in the database (using BinaryFormatter to serialize it). The AddPost() method is used to add rolls to the post, and Validate() is used to determine if the post has been modified in a way that indicates cheating. Even if you do not care about the cheating detection, '''Validate() must be called before serializing a RollPost.''' If you do not do this, the Pristine version of the roll will not be updated, which can cause issues down the line for future edits causing expressions to be rerolled instead of taking on their prior values.
+When a new post is made, a new RollPost instance should be constructed and stored along with that post in the database (using the [[/Serialize|Serialize()]] method, it is recommended that a DeflateStream is passed or some other compression stream). The AddPost() method is used to add rolls to the post, and Validate() is used to determine if the post has been modified in a way that indicates cheating. Even if you do not care about the cheating detection, '''Validate() must be called before serializing a RollPost.''' If you do not do this, the Pristine version of the roll will not be updated, which can cause issues down the line for future edits causing expressions to be rerolled instead of taking on their prior values.
-When processing an existing post, deserialize the stored RollPost, then call AddRoll() again for all rolls in the post. RollPost will re-use previously rolled values for those rolls if possible, otherwise it will reroll them. After all rolls have been added via AddRoll(), Validate() should be called to determine whether or not cheating happened and to update some internal state, and then you can iterate over Current to retrieve all of the individual [[Dice/RollResult|RollResults]].
+When processing an existing post, deserialize the stored RollPost via [[/Deserialize|RollPost.Deserialize()]], then call AddRoll() again for all rolls in the post. RollPost will re-use previously rolled values for those rolls if possible, otherwise it will reroll them. After all rolls have been added via AddRoll(), Validate() should be called to determine whether or not cheating happened and to update some internal state, and then you can iterate over Current to retrieve all of the individual [[Dice/RollResult|RollResults]].
 == Examples ==
@@ Line 87: / Line 96: @@
 using System;
 using System.IO;
-using System.Runtime.Serialization.Formatters.Binary;
+using System.IO.Compression;
 using Dice;
@@ Line 96: / Line 105: @@
      public static void Main()
+     {
          MemoryStream stream = new MemoryStream();
@@ Line 105: / Line 113: @@
          post.Validate(); // must be called every time, including on initial post
-         formatter.Serialize(stream, post);
+         // passing true as 3rd param leaves stream open, otherwise DeflateStream closes it
          // save contents of stream along with the post to the database...
          // for this example we just rewind the stream
@@ Line 111: / Line 124: @@
          // later: retrieve serialized post from database, store it in stream...
-         post = (RollPost)formatter.Deserialize(stream);
+         using (var deflate = new DeflateStream(stream, CompressionMode.Decompress))
          // need to re-add the rolls on the current version of the post,
          // even if they didn't change

← Older revision		Revision as of 23:12, 19 April 2017
Line 80:		Line 80:

	When processing an existing post, deserialize the stored RollPost, then call AddRoll() again for all rolls in the post. RollPost will re-use previously rolled values for those rolls if possible, otherwise it will reroll them. After all rolls have been added via AddRoll(), Validate() should be called to determine whether or not cheating happened and to update some internal state, and then you can iterate over Current to retrieve all of the individual [[Dice/RollResult\|RollResults]].		When processing an existing post, deserialize the stored RollPost, then call AddRoll() again for all rolls in the post. RollPost will re-use previously rolled values for those rolls if possible, otherwise it will reroll them. After all rolls have been added via AddRoll(), Validate() should be called to determine whether or not cheating happened and to update some internal state, and then you can iterate over Current to retrieve all of the individual [[Dice/RollResult\|RollResults]].
		+
		+	== Examples ==
		+	The following example simulates creating and saving a new post, and then later loading it to inspect the rolled values.
		+
		+	<syntaxhighlight lang="C#">
		+	using System;
		+	using System.IO;
		+	using System.Runtime.Serialization.Formatters.Binary;
		+
		+	using Dice;
		+	using Dice.PbP;
		+
		+	class Sample
		+	{
		+	public static void Main()
		+	{
		+	BinaryFormatter formatter = new BinaryFormatter();
		+	MemoryStream stream = new MemoryStream();
		+
		+	// pretend our post had 2 rolls: 1d20+4 and 2d6+3/4d6+6
		+	RollPost post = new RollPost();
		+	post.AddRoll("1d20+4");
		+	post.AddRoll("if([roll:1:critical], >0, 4d6+6, 2d6+3)");
		+	post.Validate(); // must be called every time, including on initial post
		+
		+	formatter.Serialize(stream, post);
		+	// save contents of stream along with the post to the database...
		+	// for this example we just rewind the stream
		+	stream.Seek(0, SeekOrigin.Begin);
		+
		+	// later: retrieve serialized post from database, store it in stream...
		+	post = (RollPost)formatter.Deserialize(stream);
		+	// need to re-add the rolls on the current version of the post,
		+	// even if they didn't change
		+	post.AddRoll("1d20+4");
		+	post.AddRoll("if([roll:1:critical], >0, 4d6+6, 2d6+3)");
		+	if (!post.Validate())
		+	{
		+	// if post.Validate() returns false, this indicates that the rolls were
		+	// tampered with. Highlight this somehow on the post (perhaps with a scary
		+	// warning sign in the post background).
		+	}
		+
		+	// iterate over the results so we can display them
		+	foreach (RollResult result in post.Current)
		+	{
		+	Console.WriteLine(result.ToString());
		+	}
		+	}
		+	}
		+	</syntaxhighlight>