1 // Protocol Buffers - Google's data interchange format 2 // Copyright 2024 Google Inc. All rights reserved. 3 // 4 // Use of this source code is governed by a BSD-style 5 // license that can be found in the LICENSE file or at 6 // https://developers.google.com/open-source/licenses/bsd 7 8 #import <Foundation/Foundation.h> 9 10 #import "GPBMessage.h" 11 #import "GPBUnknownField.h" 12 13 @class GPBMessage; 14 @class GPBUnknownField; 15 16 NS_ASSUME_NONNULL_BEGIN 17 18 /** 19 * A collection of unknown field numbers and their values. 20 * 21 * Note: `NSFastEnumeration` is supported to iterate over the `GPBUnknownFields` 22 * in order. 23 * 24 * Reminder: Any field number can occur multiple times. For example, if a .proto 25 * file were updated to a have a new (unpacked) repeated field, then each value 26 * would appear independently. Likewise, it is possible that a number appears 27 * multiple times with different data types, i.e. - unpacked vs. package repeated 28 * fields from concatenating binary blobs of data. 29 */ 30 __attribute__((objc_subclassing_restricted)) 31 @interface GPBUnknownFields : NSObject<NSCopying, NSFastEnumeration> 32 33 /** 34 * Initializes a new instance with the data from the unknown fields from the given 35 * message. 36 * 37 * Note: The instance is not linked to the message, any change will not be 38 * reflected on the message the changes have to be pushed back to the message 39 * with `-[GPBMessage mergeUnknownFields:extensionRegistry:error:]`. 40 **/ 41 - (instancetype)initFromMessage:(nonnull GPBMessage *)message; 42 43 /** 44 * Initializes a new empty instance. 45 **/ 46 - (instancetype)init; 47 48 /** 49 * The number of fields in this set. A single field number can appear in 50 * multiple `GPBUnknownField` values as it might be a repeated field (it is 51 * also possible that they have different `type` values (for example package vs 52 * unpacked repeated fields). 53 * 54 * Note: `NSFastEnumeration` is supported to iterate over the fields in order. 55 **/ 56 @property(nonatomic, readonly, assign) NSUInteger count; 57 58 /** If the set is empty or not. */ 59 @property(nonatomic, readonly, assign) BOOL empty; 60 61 /** 62 * Removes all the fields current in the set. 63 **/ 64 - (void)clear; 65 66 /** 67 * Fetches the subset of all the unknown fields that are for the given field 68 * number. 69 * 70 * @returns An `NSArray` of `GPBUnknownField`s or `nil` if there were none. 71 */ 72 - (nullable NSArray<GPBUnknownField *> *)fields:(int32_t)fieldNumber; 73 74 /** 75 * Add a new varint unknown field. 76 * 77 * @param fieldNumber The field number to use. 78 * @param value The value to add. 79 **/ 80 - (void)addFieldNumber:(int32_t)fieldNumber varint:(uint64_t)value; 81 82 /** 83 * Add a new fixed32 unknown field. 84 * 85 * @param fieldNumber The field number to use. 86 * @param value The value to add. 87 **/ 88 - (void)addFieldNumber:(int32_t)fieldNumber fixed32:(uint32_t)value; 89 90 /** 91 * Add a new fixed64 unknown field. 92 * 93 * @param fieldNumber The field number to use. 94 * @param value The value to add. 95 **/ 96 - (void)addFieldNumber:(int32_t)fieldNumber fixed64:(uint64_t)value; 97 98 /** 99 * Add a new length delimited (length prefixed) unknown field. 100 * 101 * @param fieldNumber The field number to use. 102 * @param value The value to add. 103 **/ 104 - (void)addFieldNumber:(int32_t)fieldNumber lengthDelimited:(nonnull NSData *)value; 105 106 /** 107 * Add a group (tag delimited) unknown field. 108 * 109 * @param fieldNumber The field number to use. 110 * 111 * @return A new `GPBUnknownFields` to set the field of the group too. 112 **/ 113 - (nonnull GPBUnknownFields *)addGroupWithFieldNumber:(int32_t)fieldNumber; 114 115 /** 116 * Add the copy of the given unknown field. 117 * 118 * This can be useful from processing one `GPBUnknownFields` to create another. 119 * 120 * NOTE: If the field being copied is an Group, this instance added is new and thus 121 * the `.group` of that result is also new, so if you intent is to modify the group 122 * it *must* be fetched out of the result. 123 * 124 * It is a programming error to call this when the `type` is a legacy field. 125 * 126 * @param field The field to add. 127 * 128 * @return The autoreleased field that was added. 129 **/ 130 - (GPBUnknownField *)addCopyOfField:(nonnull GPBUnknownField *)field; 131 132 /** 133 * Removes the given field from the set. 134 * 135 * It is a programming error to attempt to remove a field that is not in this collection. 136 * 137 * Reminder: it is not save to mutate the collection while also using fast enumeration on it. 138 * 139 * @param field The field to remove. 140 **/ 141 - (void)removeField:(nonnull GPBUnknownField *)field; 142 143 /** 144 * Removes all of the fields from the collection that have the given field number. 145 * 146 * If there are no fields with the given field number, this is a no-op. 147 * 148 * @param fieldNumber The field number to remove. 149 **/ 150 - (void)clearFieldNumber:(int32_t)fieldNumber; 151 152 @end 153 154 @interface GPBUnknownFields (AccessHelpers) 155 156 /** 157 * Fetches the first varint for the given field number. 158 * 159 * @param fieldNumber The field number to look for. 160 * @param outValue A pointer to receive the value if found 161 * 162 * @returns YES/NO on if there was a matching unknown field. 163 **/ 164 - (BOOL)getFirst:(int32_t)fieldNumber varint:(nonnull uint64_t *)outValue; 165 166 /** 167 * Fetches the first fixed32 for the given field number. 168 * 169 * @param fieldNumber The field number to look for. 170 * @param outValue A pointer to receive the value if found 171 * 172 * @returns YES/NO on if there was a matching unknown field. 173 **/ 174 - (BOOL)getFirst:(int32_t)fieldNumber fixed32:(nonnull uint32_t *)outValue; 175 176 /** 177 * Fetches the first fixed64 for the given field number. 178 * 179 * @param fieldNumber The field number to look for. 180 * @param outValue A pointer to receive the value if found 181 * 182 * @returns YES/NO on if there was a matching unknown field. 183 **/ 184 - (BOOL)getFirst:(int32_t)fieldNumber fixed64:(nonnull uint64_t *)outValue; 185 186 /** 187 * Fetches the first length delimited (length prefixed) for the given field number. 188 * 189 * @param fieldNumber The field number to look for. 190 * 191 * @returns The first length delimited value for the given field number. 192 **/ 193 - (nullable NSData *)firstLengthDelimited:(int32_t)fieldNumber; 194 195 /** 196 * Fetches the first group (tag delimited) field for the given field number. 197 * 198 * @param fieldNumber The field number to look for. 199 * 200 * @returns The first group for the given field number. 201 **/ 202 - (nullable GPBUnknownFields *)firstGroup:(int32_t)fieldNumber; 203 204 @end 205 206 NS_ASSUME_NONNULL_END 207