1#region Copyright notice and license
2// Protocol Buffers - Google's data interchange format
3// Copyright 2008 Google Inc.  All rights reserved.
4// https://developers.google.com/protocol-buffers/
5//
6// Redistribution and use in source and binary forms, with or without
7// modification, are permitted provided that the following conditions are
8// met:
9//
10//     * Redistributions of source code must retain the above copyright
11// notice, this list of conditions and the following disclaimer.
12//     * Redistributions in binary form must reproduce the above
13// copyright notice, this list of conditions and the following disclaimer
14// in the documentation and/or other materials provided with the
15// distribution.
16//     * Neither the name of Google Inc. nor the names of its
17// contributors may be used to endorse or promote products derived from
18// this software without specific prior written permission.
19//
20// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
21// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
22// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
23// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
24// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
25// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
26// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
27// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
28// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
30// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31#endregion
32
33using Google.Protobuf.Collections;
34using System;
35using System.Collections.Generic;
36
37namespace Google.Protobuf.Reflection
38{
39    /// <summary>
40    /// Descriptor for an enum type in a .proto file.
41    /// </summary>
42    public sealed class EnumDescriptor : DescriptorBase
43    {
44        private readonly EnumDescriptorProto proto;
45        private readonly MessageDescriptor containingType;
46        private readonly IList<EnumValueDescriptor> values;
47        private readonly Type clrType;
48
49        internal EnumDescriptor(EnumDescriptorProto proto, FileDescriptor file, MessageDescriptor parent, int index, Type clrType)
50            : base(file, file.ComputeFullName(parent, proto.Name), index)
51        {
52            this.proto = proto;
53            this.clrType = clrType;
54            containingType = parent;
55
56            if (proto.Value.Count == 0)
57            {
58                // We cannot allow enums with no values because this would mean there
59                // would be no valid default value for fields of this type.
60                throw new DescriptorValidationException(this, "Enums must contain at least one value.");
61            }
62
63            values = DescriptorUtil.ConvertAndMakeReadOnly(proto.Value,
64                                                           (value, i) => new EnumValueDescriptor(value, file, this, i));
65
66            File.DescriptorPool.AddSymbol(this);
67        }
68
69        internal EnumDescriptorProto Proto { get { return proto; } }
70
71        /// <summary>
72        /// The brief name of the descriptor's target.
73        /// </summary>
74        public override string Name { get { return proto.Name; } }
75
76        internal override IReadOnlyList<DescriptorBase> GetNestedDescriptorListForField(int fieldNumber)
77        {
78            switch (fieldNumber)
79            {
80                case EnumDescriptorProto.ValueFieldNumber:
81                    return (IReadOnlyList<DescriptorBase>) Values;
82                default:
83                    return null;
84            }
85        }
86
87        /// <summary>
88        /// The CLR type for this enum. For generated code, this will be a CLR enum type.
89        /// </summary>
90        public Type ClrType { get { return clrType; } }
91
92        /// <value>
93        /// If this is a nested type, get the outer descriptor, otherwise null.
94        /// </value>
95        public MessageDescriptor ContainingType
96        {
97            get { return containingType; }
98        }
99
100        /// <value>
101        /// An unmodifiable list of defined value descriptors for this enum.
102        /// </value>
103        public IList<EnumValueDescriptor> Values
104        {
105            get { return values; }
106        }
107
108        /// <summary>
109        /// Finds an enum value by number. If multiple enum values have the
110        /// same number, this returns the first defined value with that number.
111        /// If there is no value for the given number, this returns <c>null</c>.
112        /// </summary>
113        public EnumValueDescriptor FindValueByNumber(int number)
114        {
115            return File.DescriptorPool.FindEnumValueByNumber(this, number);
116        }
117
118        /// <summary>
119        /// Finds an enum value by name.
120        /// </summary>
121        /// <param name="name">The unqualified name of the value (e.g. "FOO").</param>
122        /// <returns>The value's descriptor, or null if not found.</returns>
123        public EnumValueDescriptor FindValueByName(string name)
124        {
125            return File.DescriptorPool.FindSymbol<EnumValueDescriptor>(FullName + "." + name);
126        }
127
128        /// <summary>
129        /// The (possibly empty) set of custom options for this enum.
130        /// </summary>
131        [Obsolete("CustomOptions are obsolete. Use the GetOptions() method.")]
132        public CustomOptions CustomOptions => new CustomOptions(Proto.Options?._extensions?.ValuesByNumber);
133
134        /// <summary>
135        /// The <c>EnumOptions</c>, defined in <c>descriptor.proto</c>.
136        /// If the options message is not present (i.e. there are no options), <c>null</c> is returned.
137        /// Custom options can be retrieved as extensions of the returned message.
138        /// NOTE: A defensive copy is created each time this property is retrieved.
139        /// </summary>
140        public EnumOptions GetOptions() => Proto.Options?.Clone();
141
142        /// <summary>
143        /// Gets a single value enum option for this descriptor
144        /// </summary>
145        [Obsolete("GetOption is obsolete. Use the GetOptions() method.")]
146        public T GetOption<T>(Extension<EnumOptions, T> extension)
147        {
148            var value = Proto.Options.GetExtension(extension);
149            return value is IDeepCloneable<T> ? (value as IDeepCloneable<T>).Clone() : value;
150        }
151
152        /// <summary>
153        /// Gets a repeated value enum option for this descriptor
154        /// </summary>
155        [Obsolete("GetOption is obsolete. Use the GetOptions() method.")]
156        public RepeatedField<T> GetOption<T>(RepeatedExtension<EnumOptions, T> extension)
157        {
158            return Proto.Options.GetExtension(extension).Clone();
159        }
160    }
161}