diff options
Diffstat (limited to 'cs-dotnet/src/gatsstream.cs')
-rw-r--r-- | cs-dotnet/src/gatsstream.cs | 57 |
1 files changed, 57 insertions, 0 deletions
diff --git a/cs-dotnet/src/gatsstream.cs b/cs-dotnet/src/gatsstream.cs index e1bba91..742f0b4 100644 --- a/cs-dotnet/src/gatsstream.cs +++ b/cs-dotnet/src/gatsstream.cs | |||
@@ -11,6 +11,23 @@ using System; | |||
11 | 11 | ||
12 | namespace Com.Xagasoft.Gats | 12 | namespace Com.Xagasoft.Gats |
13 | { | 13 | { |
14 | /// <summary> | ||
15 | /// Main I/O interface. Use this to read and write GATS. | ||
16 | /// </summary> | ||
17 | /// <remarks> | ||
18 | /// GatsStream is not a traditional Stream class, it only can read and | ||
19 | /// write complete GATS packets. A GATS packet consists of a version, | ||
20 | /// size, and a single encoded GATS object (which can be a container). | ||
21 | /// | ||
22 | /// This one class handles both reading and writing. Writing is fairly | ||
23 | /// straight forward, but for volatile streams like network sockets you'll | ||
24 | /// probably want to wrap your stream with a buffer before handing it to | ||
25 | /// GatsStream. | ||
26 | /// | ||
27 | /// Reading handles it's own buffering, and will remember what has been | ||
28 | /// read between calls if it cannot get enough data at once to complete | ||
29 | /// a single packet. See the ReadObject docs for more details. | ||
30 | /// </remarks> | ||
14 | public class GatsStream | 31 | public class GatsStream |
15 | { | 32 | { |
16 | private Stream s; | 33 | private Stream s; |
@@ -20,12 +37,37 @@ namespace Com.Xagasoft.Gats | |||
20 | private BinaryWriter bw = null; | 37 | private BinaryWriter bw = null; |
21 | private BinaryReader br = null; | 38 | private BinaryReader br = null; |
22 | 39 | ||
40 | /// <summary> | ||
41 | /// Construct a new GatsStream around a given Stream class. | ||
42 | /// </summary> | ||
43 | /// <remarks> | ||
44 | /// The provided Stream does not need to be opened for both reading and | ||
45 | /// writing, you can construct a GatsStream around a read only or | ||
46 | /// write only stream. | ||
47 | /// </remarks> | ||
48 | /// <param name="s">Stream to operate on.</param> | ||
23 | public GatsStream( Stream s ) | 49 | public GatsStream( Stream s ) |
24 | { | 50 | { |
25 | this.s = s; | 51 | this.s = s; |
26 | this.ReadBuf = new MemoryStream(); | 52 | this.ReadBuf = new MemoryStream(); |
27 | } | 53 | } |
28 | 54 | ||
55 | /// <summary> | ||
56 | /// Read a GATS packet and return the contained GatsObject. | ||
57 | /// </summary> | ||
58 | /// <remarks> | ||
59 | /// This reads a complete packet into an internal buffer, parses the | ||
60 | /// gats object within it, and returns it. This method will read as | ||
61 | /// much data as it needs from the stream, but no more. Not a single | ||
62 | /// extra byte will be read. | ||
63 | /// | ||
64 | /// In the event that an end of stream is encountered, or a partial | ||
65 | /// packet has been read but no more data can be read at the moment, | ||
66 | /// this method will maintain it's buffer but return null to the caller. | ||
67 | /// </remarks> | ||
68 | /// <returns> | ||
69 | /// The read object, or null if no object could be read yet. | ||
70 | /// </returns> | ||
29 | public GatsObject ReadObject() | 71 | public GatsObject ReadObject() |
30 | { | 72 | { |
31 | if( size == -1 ) | 73 | if( size == -1 ) |
@@ -70,6 +112,21 @@ namespace Com.Xagasoft.Gats | |||
70 | return null; | 112 | return null; |
71 | } | 113 | } |
72 | 114 | ||
115 | /// <summary> | ||
116 | /// Write a GatsObject to the stream in a proper GATS packet. | ||
117 | /// </summary> | ||
118 | /// <remarks> | ||
119 | /// The object passed in is first written to an internal buffer, and | ||
120 | /// then to the output in several write operations. This means that | ||
121 | /// for many applications you will want to buffer the output. In the | ||
122 | /// case of writing to files, it could be faster to buffer the output. | ||
123 | /// In the case of writing to a socket buffering could prevent sending | ||
124 | /// many small packets. | ||
125 | /// | ||
126 | /// No flushing is done by this method, it is left to the caller to | ||
127 | /// determine the proper time to flush their streams. | ||
128 | /// </remarks> | ||
129 | /// <param name="obj">The object to be written.</param> | ||
73 | public void WriteObject( GatsObject obj ) | 130 | public void WriteObject( GatsObject obj ) |
74 | { | 131 | { |
75 | MemoryStream ms = new MemoryStream(); | 132 | MemoryStream ms = new MemoryStream(); |