blob: e87bb52cd5e546dc3f8bfb571e4550f7640342ab [file] [log] [blame]
Jon Skeet60c059b2008-10-23 21:17:56 +01001// Protocol Buffers - Google's data interchange format
2// Copyright 2008 Google Inc. All rights reserved.
3// http://github.com/jskeet/dotnet-protobufs/
4// Original C++/Java/Python code:
Jon Skeet68036862008-10-22 13:30:34 +01005// http://code.google.com/p/protobuf/
6//
Jon Skeet60c059b2008-10-23 21:17:56 +01007// Redistribution and use in source and binary forms, with or without
8// modification, are permitted provided that the following conditions are
9// met:
Jon Skeet68036862008-10-22 13:30:34 +010010//
Jon Skeet60c059b2008-10-23 21:17:56 +010011// * Redistributions of source code must retain the above copyright
12// notice, this list of conditions and the following disclaimer.
13// * Redistributions in binary form must reproduce the above
14// copyright notice, this list of conditions and the following disclaimer
15// in the documentation and/or other materials provided with the
16// distribution.
17// * Neither the name of Google Inc. nor the names of its
18// contributors may be used to endorse or promote products derived from
19// this software without specific prior written permission.
Jon Skeet68036862008-10-22 13:30:34 +010020//
Jon Skeet60c059b2008-10-23 21:17:56 +010021// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
22// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
23// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
24// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
25// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
26// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
27// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
28// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
29// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
30// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
31// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Jon Skeet68036862008-10-22 13:30:34 +010032using System;
33using System.Collections.Generic;
34using System.IO;
35using Google.ProtocolBuffers.Descriptors;
36
37namespace Google.ProtocolBuffers {
38
39 /// <summary>
40 /// Non-generic interface used for all parts of the API which don't require
41 /// any type knowledge.
42 /// </summary>
43 public interface IMessage {
44 /// <summary>
45 /// Returns the message's type's descriptor. This differs from the
46 /// Descriptor property of each generated message class in that this
47 /// method is an abstract method of IMessage whereas Descriptor is
48 /// a static property of a specific class. They return the same thing.
49 /// </summary>
50 MessageDescriptor DescriptorForType { get; }
51 /// <summary>
52 /// Returns a collection of all the fields in this message which are set
53 /// and their corresponding values. A singular ("required" or "optional")
54 /// field is set iff HasField() returns true for that field. A "repeated"
55 /// field is set iff GetRepeatedFieldSize() is greater than zero. The
56 /// values are exactly what would be returned by calling
57 /// GetField(FieldDescriptor) for each field. The map
58 /// is guaranteed to be a sorted map, so iterating over it will return fields
59 /// in order by field number.
60 /// </summary>
61 IDictionary<FieldDescriptor, object> AllFields { get; }
62
63 /// <summary>
64 /// Returns true if the given field is set. This is exactly equivalent
65 /// to calling the generated "Has" property corresponding to the field.
66 /// </summary>
67 /// <exception cref="ArgumentException">the field is a repeated field,
68 /// or it's not a field of this type</exception>
69 bool HasField(FieldDescriptor field);
70
71 /// <summary>
72 /// Obtains the value of the given field, or the default value if
73 /// it isn't set. For value type fields, the boxed value is returned.
74 /// For enum fields, the EnumValueDescriptor for the enum is returned.
75 /// For embedded message fields, the sub-message
76 /// is returned. For repeated fields, an IList&lt;T&gt; is returned.
77 /// </summary>
78 object this[FieldDescriptor field] { get; }
79
80 /// <summary>
81 /// Returns the number of elements of a repeated field. This is
82 /// exactly equivalent to calling the generated "Count" property
83 /// corresponding to the field.
84 /// </summary>
85 /// <exception cref="ArgumentException">the field is not a repeated field,
86 /// or it's not a field of this type</exception>
87 int GetRepeatedFieldCount(FieldDescriptor field);
88
89 /// <summary>
90 /// Gets an element of a repeated field. For value type fields
Jon Skeeta3767342009-01-16 18:06:56 +000091 /// excluding enums, the boxed value is returned. For embedded
92 /// message fields, the sub-message is returned. For enums, the
93 /// relevant EnumValueDescriptor is returned.
Jon Skeet68036862008-10-22 13:30:34 +010094 /// </summary>
95 /// <exception cref="ArgumentException">the field is not a repeated field,
96 /// or it's not a field of this type</exception>
97 /// <exception cref="ArgumentOutOfRangeException">the index is out of
98 /// range for the repeated field's value</exception>
99 object this[FieldDescriptor field, int index] { get; }
100
101 /// <summary>
102 /// Returns the unknown fields for this message.
103 /// </summary>
104 UnknownFieldSet UnknownFields { get; }
105
106 /// <summary>
107 /// Returns true iff all required fields in the message and all embedded
108 /// messages are set.
109 /// </summary>
110 bool IsInitialized { get; }
111
112 /// <summary>
113 /// Serializes the message and writes it to the given output stream.
114 /// This does not flush or close the stream.
115 /// </summary>
116 /// <param name="output"></param>
117 void WriteTo(CodedOutputStream output);
118
119 /// <summary>
120 /// Returns the number of bytes required to encode this message.
121 /// The result is only computed on the first call and memoized after that.
122 /// </summary>
123 int SerializedSize { get; }
124
125 #region Comparison and hashing
126 /// <summary>
127 /// Compares the specified object with this message for equality.
128 /// Returns true iff the given object is a message of the same type
129 /// (as defined by DescriptorForType) and has identical values
130 /// for all its fields.
131 /// </summary>
132 bool Equals(object other);
133
134 /// <summary>
135 /// Returns the hash code value for this message.
136 /// TODO(jonskeet): Specify the hash algorithm, but better than the Java one!
137 /// </summary>
138 int GetHashCode();
139 #endregion
140
141 #region Convenience methods
142 /// <summary>
143 /// Converts the message to a string in protocol buffer text format.
144 /// This is just a trivial wrapper around TextFormat.PrintToString.
145 /// </summary>
146 string ToString();
147
148 /// <summary>
149 /// Serializes the message to a ByteString. This is a trivial wrapper
150 /// around WriteTo(CodedOutputStream).
151 /// </summary>
152 ByteString ToByteString();
153
154 /// <summary>
155 /// Serializes the message to a byte array. This is a trivial wrapper
156 /// around WriteTo(CodedOutputStream).
157 /// </summary>
158 byte[] ToByteArray();
159
160 /// <summary>
161 /// Serializes the message and writes it to the given stream.
162 /// This is just a wrapper around WriteTo(CodedOutputStream). This
163 /// does not flush or close the stream.
164 /// </summary>
165 /// <param name="output"></param>
166 void WriteTo(Stream output);
167 #endregion
168
169 /// <summary>
170 /// Creates a builder for the type, but in a weakly typed manner. This
Jon Skeete81a9d72009-02-24 16:50:56 +0000171 /// is typically implemented by strongly typed messages by just returning
Jon Skeet68036862008-10-22 13:30:34 +0100172 /// the result of CreateBuilderForType.
173 /// </summary>
174 IBuilder WeakCreateBuilderForType();
175
Jon Skeete81a9d72009-02-24 16:50:56 +0000176 /// <summary>
177 /// Creates a builder with the same contents as this message. This
178 /// is typically implemented by strongly typed messages by just returning
179 /// the result of ToBuilder.
180 /// </summary>
181 IBuilder WeakToBuilder();
182
Jon Skeet68036862008-10-22 13:30:34 +0100183 IMessage WeakDefaultInstanceForType { get; }
184 }
185
186 public interface IMessage<TMessage> : IMessage {
187 /// <summary>
188 /// Returns an instance of this message type with all fields set to
189 /// their default values. This may or may not be a singleton. This differs
190 /// from the DefaultInstance property of each generated message class in that this
191 /// method is an abstract method of IMessage whereas DefaultInstance is
192 /// a static property of a specific class. They return the same thing.
193 /// </summary>
194 TMessage DefaultInstanceForType { get; }
195 }
196
197 /// <summary>
198 /// Type-safe interface for all generated messages to implement.
199 /// </summary>
200 public interface IMessage<TMessage, TBuilder> : IMessage<TMessage>
201 where TMessage : IMessage<TMessage, TBuilder>
202 where TBuilder : IBuilder<TMessage, TBuilder> {
203 #region Builders
204 /// <summary>
205 /// Constructs a new builder for a message of the same type as this message.
206 /// </summary>
207 TBuilder CreateBuilderForType();
Jon Skeete81a9d72009-02-24 16:50:56 +0000208 /// <summary>
209 /// Creates a builder with the same contents as this current instance.
210 /// This is typically implemented by strongly typed messages by just
211 /// returning the result of ToBuilder().
212 /// </summary>
213 TBuilder ToBuilder();
Jon Skeet68036862008-10-22 13:30:34 +0100214 #endregion
215 }
216}