From 2cbd799b5e548e1e6fb66b86aaf8f53b5f38b62f Mon Sep 17 00:00:00 2001 From: Jon Skeet Date: Fri, 15 Aug 2008 21:24:06 +0100 Subject: Comments. --- csharp/ProtocolBuffers/ExtensionRegistry.cs | 52 +++++++++++++++++++++- csharp/ProtocolBuffers/IBuilder.cs | 1 - .../InvalidProtocolBufferException.cs | 3 +- 3 files changed, 51 insertions(+), 5 deletions(-) (limited to 'csharp') diff --git a/csharp/ProtocolBuffers/ExtensionRegistry.cs b/csharp/ProtocolBuffers/ExtensionRegistry.cs index c9e05308..dec75733 100644 --- a/csharp/ProtocolBuffers/ExtensionRegistry.cs +++ b/csharp/ProtocolBuffers/ExtensionRegistry.cs @@ -19,8 +19,56 @@ using System; namespace Google.ProtocolBuffers { /// - /// TODO(jonskeet): Copy docs from Java + /// A table of known extensions, searchable by name or field number. When + /// parsing a protocol message that might have extensions, you must provide + /// an in which you have registered any extensions + /// that you want to be able to parse. Otherwise, those extensions will just + /// be treated like unknown fields. /// + /// + /// For example, if you had the .proto file: + /// + /// option java_class = "MyProto"; + /// + /// message Foo { + /// extensions 1000 to max; + /// } + /// + /// extend Foo { + /// optional int32 bar; + /// } + /// + /// + /// Then you might write code like: + /// + /// + /// ExtensionRegistry registry = ExtensionRegistry.CreateInstance(); + /// registry.Add(MyProto.Bar); + /// MyProto.Foo message = MyProto.Foo.ParseFrom(input, registry); + /// + /// + /// + /// + /// You might wonder why this is necessary. Two alternatives might come to + /// mind. First, you might imagine a system where generated extensions are + /// automatically registered when their containing classes are loaded. This + /// is a popular technique, but is bad design; among other things, it creates a + /// situation where behavior can change depending on what classes happen to be + /// loaded. It also introduces a security vulnerability, because an + /// unprivileged class could cause its code to be called unexpectedly from a + /// privileged class by registering itself as an extension of the right type. + /// + /// Another option you might consider is lazy parsing: do not parse an + /// extension until it is first requested, at which point the caller must + /// provide a type to use. This introduces a different set of problems. First, + /// it would require a mutex lock any time an extension was accessed, which + /// would be slow. Second, corrupt data would not be detected until first + /// access, at which point it would be much harder to deal with it. Third, it + /// could violate the expectation that message objects are immutable, since the + /// type provided could be any arbitrary message class. An unprivileged user + /// could take advantage of this to inject a mutable object into a message + /// belonging to privileged code and create mischief. + /// public sealed class ExtensionRegistry { private static readonly ExtensionRegistry empty = new ExtensionRegistry( @@ -140,7 +188,7 @@ namespace Google.ProtocolBuffers { && field.IsOptional && field.ExtensionScope == field.MessageType) { // This is an extension of a MessageSet type defined within the extension - // type's own scope. For backwards-compatibility, allow it to be looked + // type's own scope. For backwards-compatibility, allow it to be looked // up by type name. extensionsByName[field.MessageType.FullName] = extension; } diff --git a/csharp/ProtocolBuffers/IBuilder.cs b/csharp/ProtocolBuffers/IBuilder.cs index 44990792..0693d088 100644 --- a/csharp/ProtocolBuffers/IBuilder.cs +++ b/csharp/ProtocolBuffers/IBuilder.cs @@ -233,7 +233,6 @@ namespace Google.ProtocolBuffers { TBuilder MergeUnknownFields(UnknownFieldSet unknownFields); #region Convenience methods - // TODO(jonskeet): Implement these as extension methods? /// /// Parse as a message of this type and merge /// it with the message being built. This is just a small wrapper around diff --git a/csharp/ProtocolBuffers/InvalidProtocolBufferException.cs b/csharp/ProtocolBuffers/InvalidProtocolBufferException.cs index 334a416a..10257542 100644 --- a/csharp/ProtocolBuffers/InvalidProtocolBufferException.cs +++ b/csharp/ProtocolBuffers/InvalidProtocolBufferException.cs @@ -26,8 +26,7 @@ namespace Google.ProtocolBuffers { : base(message) { } - /// TODO(jonskeet): Make this internal again and use InternalVisibleTo? - public static InvalidProtocolBufferException TruncatedMessage() { + internal static InvalidProtocolBufferException TruncatedMessage() { return new InvalidProtocolBufferException( "While parsing a protocol message, the input ended unexpectedly " + "in the middle of a field. This could mean either than the " + -- cgit v1.2.3