1 #region Copyright notice and license 2 // Protocol Buffers - Google's data interchange format 3 // Copyright 2008 Google Inc. All rights reserved. 4 // 5 // Use of this source code is governed by a BSD-style 6 // license that can be found in the LICENSE file or at 7 // https://developers.google.com/open-source/licenses/bsd 8 #endregion 9 10 using Google.Protobuf.Collections; 11 using System; 12 using System.Collections.Generic; 13 14 namespace Google.Protobuf.Reflection 15 { 16 /// <summary> 17 /// Descriptor for an enum type in a .proto file. 18 /// </summary> 19 public sealed class EnumDescriptor : DescriptorBase 20 { EnumDescriptor(EnumDescriptorProto proto, FileDescriptor file, MessageDescriptor parent, int index, Type clrType)21 internal EnumDescriptor(EnumDescriptorProto proto, FileDescriptor file, MessageDescriptor parent, int index, Type clrType) 22 : base(file, file.ComputeFullName(parent, proto.Name), index, (parent?.Features ?? file.Features).MergedWith(proto.Options?.Features)) 23 { 24 Proto = proto; 25 ClrType = clrType; 26 ContainingType = parent; 27 28 if (proto.Value.Count == 0) 29 { 30 // We cannot allow enums with no values because this would mean there 31 // would be no valid default value for fields of this type. 32 throw new DescriptorValidationException(this, "Enums must contain at least one value."); 33 } 34 35 Values = DescriptorUtil.ConvertAndMakeReadOnly(proto.Value, 36 (value, i) => new EnumValueDescriptor(value, file, this, i)); 37 38 File.DescriptorPool.AddSymbol(this); 39 } 40 41 internal EnumDescriptorProto Proto { get; } 42 43 /// <summary> 44 /// Returns a clone of the underlying <see cref="EnumDescriptorProto"/> describing this enum. 45 /// Note that a copy is taken every time this method is called, so clients using it frequently 46 /// (and not modifying it) may want to cache the returned value. 47 /// </summary> 48 /// <returns>A protobuf representation of this enum descriptor.</returns> ToProto()49 public EnumDescriptorProto ToProto() => Proto.Clone(); 50 51 /// <summary> 52 /// The brief name of the descriptor's target. 53 /// </summary> 54 public override string Name => Proto.Name; 55 GetNestedDescriptorListForField(int fieldNumber)56 internal override IReadOnlyList<DescriptorBase> GetNestedDescriptorListForField(int fieldNumber) => 57 fieldNumber switch 58 { 59 EnumDescriptorProto.ValueFieldNumber => (IReadOnlyList<DescriptorBase>)Values, 60 _ => null, 61 }; 62 63 /// <summary> 64 /// The CLR type for this enum. For generated code, this will be a CLR enum type. 65 /// </summary> 66 public Type ClrType { get; } 67 68 /// <value> 69 /// If this is a nested type, get the outer descriptor, otherwise null. 70 /// </value> 71 public MessageDescriptor ContainingType { get; } 72 73 /// <value> 74 /// An unmodifiable list of defined value descriptors for this enum. 75 /// </value> 76 public IList<EnumValueDescriptor> Values { get; } 77 78 /// <summary> 79 /// Finds an enum value by number. If multiple enum values have the 80 /// same number, this returns the first defined value with that number. 81 /// If there is no value for the given number, this returns <c>null</c>. 82 /// </summary> FindValueByNumber(int number)83 public EnumValueDescriptor FindValueByNumber(int number) 84 { 85 return File.DescriptorPool.FindEnumValueByNumber(this, number); 86 } 87 88 /// <summary> 89 /// Finds an enum value by name. 90 /// </summary> 91 /// <param name="name">The unqualified name of the value (e.g. "FOO").</param> 92 /// <returns>The value's descriptor, or null if not found.</returns> FindValueByName(string name)93 public EnumValueDescriptor FindValueByName(string name) => 94 File.DescriptorPool.FindEnumValueByName(this, name); 95 96 /// <summary> 97 /// The (possibly empty) set of custom options for this enum. 98 /// </summary> 99 [Obsolete("CustomOptions are obsolete. Use the GetOptions() method.")] 100 public CustomOptions CustomOptions => new CustomOptions(Proto.Options?._extensions?.ValuesByNumber); 101 102 /// <summary> 103 /// The <c>EnumOptions</c>, defined in <c>descriptor.proto</c>. 104 /// If the options message is not present (i.e. there are no options), <c>null</c> is returned. 105 /// Custom options can be retrieved as extensions of the returned message. 106 /// NOTE: A defensive copy is created each time this property is retrieved. 107 /// </summary> GetOptions()108 public EnumOptions GetOptions() 109 { 110 var clone = Proto.Options?.Clone(); 111 if (clone is null) 112 { 113 return null; 114 } 115 // Clients should be using feature accessor methods, not accessing features on the 116 // options proto. 117 clone.Features = null; 118 return clone; 119 } 120 121 /// <summary> 122 /// Gets a single value enum option for this descriptor 123 /// </summary> 124 [Obsolete("GetOption is obsolete. Use the GetOptions() method.")] GetOption(Extension<EnumOptions, T> extension)125 public T GetOption<T>(Extension<EnumOptions, T> extension) 126 { 127 var value = Proto.Options.GetExtension(extension); 128 return value is IDeepCloneable<T> ? (value as IDeepCloneable<T>).Clone() : value; 129 } 130 131 /// <summary> 132 /// Gets a repeated value enum option for this descriptor 133 /// </summary> 134 [Obsolete("GetOption is obsolete. Use the GetOptions() method.")] GetOption(RepeatedExtension<EnumOptions, T> extension)135 public RepeatedField<T> GetOption<T>(RepeatedExtension<EnumOptions, T> extension) 136 { 137 return Proto.Options.GetExtension(extension).Clone(); 138 } 139 } 140 }