iOS/Pods/Protobuf/objectivec/GPBUtilities.h

   1 // Protocol Buffers - Google's data interchange format
   2 // Copyright 2008 Google Inc.  All rights reserved.
   3 // https://developers.google.com/protocol-buffers/
   4 //
   5 // Redistribution and use in source and binary forms, with or without
   6 // modification, are permitted provided that the following conditions are
   7 // met:
   8 //
   9 //     * Redistributions of source code must retain the above copyright
  10 // notice, this list of conditions and the following disclaimer.
  11 //     * Redistributions in binary form must reproduce the above
  12 // copyright notice, this list of conditions and the following disclaimer
  13 // in the documentation and/or other materials provided with the
  14 // distribution.
  15 //     * Neither the name of Google Inc. nor the names of its
  16 // contributors may be used to endorse or promote products derived from
  17 // this software without specific prior written permission.
  18 //
  19 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  20 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  21 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  22 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  23 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  24 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  25 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  26 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  27 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  28 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  29 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  30
  31 #import <Foundation/Foundation.h>
  32
  33 #import "GPBArray.h"
  34 #import "GPBMessage.h"
  35 #import "GPBRuntimeTypes.h"
  36
  37 CF_EXTERN_C_BEGIN
  38
  39 NS_ASSUME_NONNULL_BEGIN
  40
  41 /**
  42  * Generates a string that should be a valid "TextFormat" for the C++ version
  43  * of Protocol Buffers.
  44  *
  45  * @param message    The message to generate from.
  46  * @param lineIndent A string to use as the prefix for all lines generated. Can
  47  *                   be nil if no extra indent is needed.
  48  *
  49  * @return An NSString with the TextFormat of the message.
  50  **/
  51 NSString *GPBTextFormatForMessage(GPBMessage *message,
  52                                   NSString * __nullable lineIndent);
  53
  54 /**
  55  * Generates a string that should be a valid "TextFormat" for the C++ version
  56  * of Protocol Buffers.
  57  *
  58  * @param unknownSet The unknown field set to generate from.
  59  * @param lineIndent A string to use as the prefix for all lines generated. Can
  60  *                   be nil if no extra indent is needed.
  61  *
  62  * @return An NSString with the TextFormat of the unknown field set.
  63  **/
  64 NSString *GPBTextFormatForUnknownFieldSet(GPBUnknownFieldSet * __nullable unknownSet,
  65                                           NSString * __nullable lineIndent);
  66
  67 /**
  68  * Checks if the given field number is set on a message.
  69  *
  70  * @param self        The message to check.
  71  * @param fieldNumber The field number to check.
  72  *
  73  * @return YES if the field number is set on the given message.
  74  **/
  75 BOOL GPBMessageHasFieldNumberSet(GPBMessage *self, uint32_t fieldNumber);
  76
  77 /**
  78  * Checks if the given field is set on a message.
  79  *
  80  * @param self  The message to check.
  81  * @param field The field to check.
  82  *
  83  * @return YES if the field is set on the given message.
  84  **/
  85 BOOL GPBMessageHasFieldSet(GPBMessage *self, GPBFieldDescriptor *field);
  86
  87 /**
  88  * Clears the given field for the given message.
  89  *
  90  * @param self  The message for which to clear the field.
  91  * @param field The field to clear.
  92  **/
  93 void GPBClearMessageField(GPBMessage *self, GPBFieldDescriptor *field);
  94
  95 //%PDDM-EXPAND GPB_ACCESSORS()
  96 // This block of code is generated, do not edit it directly.
  97
  98
  99 //
 100 // Get/Set a given field from/to a message.
 101 //
 102
 103 // Single Fields
 104
 105 /**
 106  * Gets the value of a bytes field.
 107  *
 108  * @param self  The message from which to get the field.
 109  * @param field The field to get.
 110  **/
 111 NSData *GPBGetMessageBytesField(GPBMessage *self, GPBFieldDescriptor *field);
 112
 113 /**
 114  * Sets the value of a bytes field.
 115  *
 116  * @param self  The message into which to set the field.
 117  * @param field The field to set.
 118  * @param value The to set in the field.
 119  **/
 120 void GPBSetMessageBytesField(GPBMessage *self, GPBFieldDescriptor *field, NSData *value);
 121
 122 /**
 123  * Gets the value of a string field.
 124  *
 125  * @param self  The message from which to get the field.
 126  * @param field The field to get.
 127  **/
 128 NSString *GPBGetMessageStringField(GPBMessage *self, GPBFieldDescriptor *field);
 129
 130 /**
 131  * Sets the value of a string field.
 132  *
 133  * @param self  The message into which to set the field.
 134  * @param field The field to set.
 135  * @param value The to set in the field.
 136  **/
 137 void GPBSetMessageStringField(GPBMessage *self, GPBFieldDescriptor *field, NSString *value);
 138
 139 /**
 140  * Gets the value of a message field.
 141  *
 142  * @param self  The message from which to get the field.
 143  * @param field The field to get.
 144  **/
 145 GPBMessage *GPBGetMessageMessageField(GPBMessage *self, GPBFieldDescriptor *field);
 146
 147 /**
 148  * Sets the value of a message field.
 149  *
 150  * @param self  The message into which to set the field.
 151  * @param field The field to set.
 152  * @param value The to set in the field.
 153  **/
 154 void GPBSetMessageMessageField(GPBMessage *self, GPBFieldDescriptor *field, GPBMessage *value);
 155
 156 /**
 157  * Gets the value of a group field.
 158  *
 159  * @param self  The message from which to get the field.
 160  * @param field The field to get.
 161  **/
 162 GPBMessage *GPBGetMessageGroupField(GPBMessage *self, GPBFieldDescriptor *field);
 163
 164 /**
 165  * Sets the value of a group field.
 166  *
 167  * @param self  The message into which to set the field.
 168  * @param field The field to set.
 169  * @param value The to set in the field.
 170  **/
 171 void GPBSetMessageGroupField(GPBMessage *self, GPBFieldDescriptor *field, GPBMessage *value);
 172
 173 /**
 174  * Gets the value of a bool field.
 175  *
 176  * @param self  The message from which to get the field.
 177  * @param field The field to get.
 178  **/
 179 BOOL GPBGetMessageBoolField(GPBMessage *self, GPBFieldDescriptor *field);
 180
 181 /**
 182  * Sets the value of a bool field.
 183  *
 184  * @param self  The message into which to set the field.
 185  * @param field The field to set.
 186  * @param value The to set in the field.
 187  **/
 188 void GPBSetMessageBoolField(GPBMessage *self, GPBFieldDescriptor *field, BOOL value);
 189
 190 /**
 191  * Gets the value of an int32 field.
 192  *
 193  * @param self  The message from which to get the field.
 194  * @param field The field to get.
 195  **/
 196 int32_t GPBGetMessageInt32Field(GPBMessage *self, GPBFieldDescriptor *field);
 197
 198 /**
 199  * Sets the value of an int32 field.
 200  *
 201  * @param self  The message into which to set the field.
 202  * @param field The field to set.
 203  * @param value The to set in the field.
 204  **/
 205 void GPBSetMessageInt32Field(GPBMessage *self, GPBFieldDescriptor *field, int32_t value);
 206
 207 /**
 208  * Gets the value of an uint32 field.
 209  *
 210  * @param self  The message from which to get the field.
 211  * @param field The field to get.
 212  **/
 213 uint32_t GPBGetMessageUInt32Field(GPBMessage *self, GPBFieldDescriptor *field);
 214
 215 /**
 216  * Sets the value of an uint32 field.
 217  *
 218  * @param self  The message into which to set the field.
 219  * @param field The field to set.
 220  * @param value The to set in the field.
 221  **/
 222 void GPBSetMessageUInt32Field(GPBMessage *self, GPBFieldDescriptor *field, uint32_t value);
 223
 224 /**
 225  * Gets the value of an int64 field.
 226  *
 227  * @param self  The message from which to get the field.
 228  * @param field The field to get.
 229  **/
 230 int64_t GPBGetMessageInt64Field(GPBMessage *self, GPBFieldDescriptor *field);
 231
 232 /**
 233  * Sets the value of an int64 field.
 234  *
 235  * @param self  The message into which to set the field.
 236  * @param field The field to set.
 237  * @param value The to set in the field.
 238  **/
 239 void GPBSetMessageInt64Field(GPBMessage *self, GPBFieldDescriptor *field, int64_t value);
 240
 241 /**
 242  * Gets the value of an uint64 field.
 243  *
 244  * @param self  The message from which to get the field.
 245  * @param field The field to get.
 246  **/
 247 uint64_t GPBGetMessageUInt64Field(GPBMessage *self, GPBFieldDescriptor *field);
 248
 249 /**
 250  * Sets the value of an uint64 field.
 251  *
 252  * @param self  The message into which to set the field.
 253  * @param field The field to set.
 254  * @param value The to set in the field.
 255  **/
 256 void GPBSetMessageUInt64Field(GPBMessage *self, GPBFieldDescriptor *field, uint64_t value);
 257
 258 /**
 259  * Gets the value of a float field.
 260  *
 261  * @param self  The message from which to get the field.
 262  * @param field The field to get.
 263  **/
 264 float GPBGetMessageFloatField(GPBMessage *self, GPBFieldDescriptor *field);
 265
 266 /**
 267  * Sets the value of a float field.
 268  *
 269  * @param self  The message into which to set the field.
 270  * @param field The field to set.
 271  * @param value The to set in the field.
 272  **/
 273 void GPBSetMessageFloatField(GPBMessage *self, GPBFieldDescriptor *field, float value);
 274
 275 /**
 276  * Gets the value of a double field.
 277  *
 278  * @param self  The message from which to get the field.
 279  * @param field The field to get.
 280  **/
 281 double GPBGetMessageDoubleField(GPBMessage *self, GPBFieldDescriptor *field);
 282
 283 /**
 284  * Sets the value of a double field.
 285  *
 286  * @param self  The message into which to set the field.
 287  * @param field The field to set.
 288  * @param value The to set in the field.
 289  **/
 290 void GPBSetMessageDoubleField(GPBMessage *self, GPBFieldDescriptor *field, double value);
 291
 292 /**
 293  * Gets the given enum field of a message. For proto3, if the value isn't a
 294  * member of the enum, @c kGPBUnrecognizedEnumeratorValue will be returned.
 295  * GPBGetMessageRawEnumField will bypass the check and return whatever value
 296  * was set.
 297  *
 298  * @param self  The message from which to get the field.
 299  * @param field The field to get.
 300  *
 301  * @return The enum value for the given field.
 302  **/
 303 int32_t GPBGetMessageEnumField(GPBMessage *self, GPBFieldDescriptor *field);
 304
 305 /**
 306  * Set the given enum field of a message. You can only set values that are
 307  * members of the enum.
 308  *
 309  * @param self  The message into which to set the field.
 310  * @param field The field to set.
 311  * @param value The enum value to set in the field.
 312  **/
 313 void GPBSetMessageEnumField(GPBMessage *self,
 314                             GPBFieldDescriptor *field,
 315                             int32_t value);
 316
 317 /**
 318  * Get the given enum field of a message. No check is done to ensure the value
 319  * was defined in the enum.
 320  *
 321  * @param self  The message from which to get the field.
 322  * @param field The field to get.
 323  *
 324  * @return The raw enum value for the given field.
 325  **/
 326 int32_t GPBGetMessageRawEnumField(GPBMessage *self, GPBFieldDescriptor *field);
 327
 328 /**
 329  * Set the given enum field of a message. You can set the value to anything,
 330  * even a value that is not a member of the enum.
 331  *
 332  * @param self  The message into which to set the field.
 333  * @param field The field to set.
 334  * @param value The raw enum value to set in the field.
 335  **/
 336 void GPBSetMessageRawEnumField(GPBMessage *self,
 337                                GPBFieldDescriptor *field,
 338                                int32_t value);
 339
 340 // Repeated Fields
 341
 342 /**
 343  * Gets the value of a repeated field.
 344  *
 345  * @param self  The message from which to get the field.
 346  * @param field The repeated field to get.
 347  *
 348  * @return A GPB*Array or an NSMutableArray based on the field's type.
 349  **/
 350 id GPBGetMessageRepeatedField(GPBMessage *self, GPBFieldDescriptor *field);
 351
 352 /**
 353  * Sets the value of a repeated field.
 354  *
 355  * @param self  The message into which to set the field.
 356  * @param field The field to set.
 357  * @param array A GPB*Array or NSMutableArray based on the field's type.
 358  **/
 359 void GPBSetMessageRepeatedField(GPBMessage *self,
 360                                 GPBFieldDescriptor *field,
 361                                 id array);
 362
 363 // Map Fields
 364
 365 /**
 366  * Gets the value of a map<> field.
 367  *
 368  * @param self  The message from which to get the field.
 369  * @param field The repeated field to get.
 370  *
 371  * @return A GPB*Dictionary or NSMutableDictionary based on the field's type.
 372  **/
 373 id GPBGetMessageMapField(GPBMessage *self, GPBFieldDescriptor *field);
 374
 375 /**
 376  * Sets the value of a map<> field.
 377  *
 378  * @param self       The message into which to set the field.
 379  * @param field      The field to set.
 380  * @param dictionary A GPB*Dictionary or NSMutableDictionary based on the
 381  *                   field's type.
 382  **/
 383 void GPBSetMessageMapField(GPBMessage *self,
 384                            GPBFieldDescriptor *field,
 385                            id dictionary);
 386
 387 //%PDDM-EXPAND-END GPB_ACCESSORS()
 388
 389 /**
 390  * Returns an empty NSData to assign to byte fields when you wish to assign them
 391  * to empty. Prevents allocating a lot of little [NSData data] objects.
 392  **/
 393 NSData *GPBEmptyNSData(void) __attribute__((pure));
 394
 395 /**
 396  * Drops the `unknownFields` from the given message and from all sub message.
 397  **/
 398 void GPBMessageDropUnknownFieldsRecursively(GPBMessage *message);
 399
 400 NS_ASSUME_NONNULL_END
 401
 402 CF_EXTERN_C_END
 403
 404
 405 //%PDDM-DEFINE GPB_ACCESSORS()
 406 //%
 407 //%//
 408 //%// Get/Set a given field from/to a message.
 409 //%//
 410 //%
 411 //%// Single Fields
 412 //%
 413 //%GPB_ACCESSOR_SINGLE_FULL(Bytes, NSData, , *)
 414 //%GPB_ACCESSOR_SINGLE_FULL(String, NSString, , *)
 415 //%GPB_ACCESSOR_SINGLE_FULL(Message, GPBMessage, , *)
 416 //%GPB_ACCESSOR_SINGLE_FULL(Group, GPBMessage, , *)
 417 //%GPB_ACCESSOR_SINGLE(Bool, BOOL, )
 418 //%GPB_ACCESSOR_SINGLE(Int32, int32_t, n)
 419 //%GPB_ACCESSOR_SINGLE(UInt32, uint32_t, n)
 420 //%GPB_ACCESSOR_SINGLE(Int64, int64_t, n)
 421 //%GPB_ACCESSOR_SINGLE(UInt64, uint64_t, n)
 422 //%GPB_ACCESSOR_SINGLE(Float, float, )
 423 //%GPB_ACCESSOR_SINGLE(Double, double, )
 424 //%/**
 425 //% * Gets the given enum field of a message. For proto3, if the value isn't a
 426 //% * member of the enum, @c kGPBUnrecognizedEnumeratorValue will be returned.
 427 //% * GPBGetMessageRawEnumField will bypass the check and return whatever value
 428 //% * was set.
 429 //% *
 430 //% * @param self  The message from which to get the field.
 431 //% * @param field The field to get.
 432 //% *
 433 //% * @return The enum value for the given field.
 434 //% **/
 435 //%int32_t GPBGetMessageEnumField(GPBMessage *self, GPBFieldDescriptor *field);
 436 //%
 437 //%/**
 438 //% * Set the given enum field of a message. You can only set values that are
 439 //% * members of the enum.
 440 //% *
 441 //% * @param self  The message into which to set the field.
 442 //% * @param field The field to set.
 443 //% * @param value The enum value to set in the field.
 444 //% **/
 445 //%void GPBSetMessageEnumField(GPBMessage *self,
 446 //%                            GPBFieldDescriptor *field,
 447 //%                            int32_t value);
 448 //%
 449 //%/**
 450 //% * Get the given enum field of a message. No check is done to ensure the value
 451 //% * was defined in the enum.
 452 //% *
 453 //% * @param self  The message from which to get the field.
 454 //% * @param field The field to get.
 455 //% *
 456 //% * @return The raw enum value for the given field.
 457 //% **/
 458 //%int32_t GPBGetMessageRawEnumField(GPBMessage *self, GPBFieldDescriptor *field);
 459 //%
 460 //%/**
 461 //% * Set the given enum field of a message. You can set the value to anything,
 462 //% * even a value that is not a member of the enum.
 463 //% *
 464 //% * @param self  The message into which to set the field.
 465 //% * @param field The field to set.
 466 //% * @param value The raw enum value to set in the field.
 467 //% **/
 468 //%void GPBSetMessageRawEnumField(GPBMessage *self,
 469 //%                               GPBFieldDescriptor *field,
 470 //%                               int32_t value);
 471 //%
 472 //%// Repeated Fields
 473 //%
 474 //%/**
 475 //% * Gets the value of a repeated field.
 476 //% *
 477 //% * @param self  The message from which to get the field.
 478 //% * @param field The repeated field to get.
 479 //% *
 480 //% * @return A GPB*Array or an NSMutableArray based on the field's type.
 481 //% **/
 482 //%id GPBGetMessageRepeatedField(GPBMessage *self, GPBFieldDescriptor *field);
 483 //%
 484 //%/**
 485 //% * Sets the value of a repeated field.
 486 //% *
 487 //% * @param self  The message into which to set the field.
 488 //% * @param field The field to set.
 489 //% * @param array A GPB*Array or NSMutableArray based on the field's type.
 490 //% **/
 491 //%void GPBSetMessageRepeatedField(GPBMessage *self,
 492 //%                                GPBFieldDescriptor *field,
 493 //%                                id array);
 494 //%
 495 //%// Map Fields
 496 //%
 497 //%/**
 498 //% * Gets the value of a map<> field.
 499 //% *
 500 //% * @param self  The message from which to get the field.
 501 //% * @param field The repeated field to get.
 502 //% *
 503 //% * @return A GPB*Dictionary or NSMutableDictionary based on the field's type.
 504 //% **/
 505 //%id GPBGetMessageMapField(GPBMessage *self, GPBFieldDescriptor *field);
 506 //%
 507 //%/**
 508 //% * Sets the value of a map<> field.
 509 //% *
 510 //% * @param self       The message into which to set the field.
 511 //% * @param field      The field to set.
 512 //% * @param dictionary A GPB*Dictionary or NSMutableDictionary based on the
 513 //% *                   field's type.
 514 //% **/
 515 //%void GPBSetMessageMapField(GPBMessage *self,
 516 //%                           GPBFieldDescriptor *field,
 517 //%                           id dictionary);
 518 //%
 519
 520 //%PDDM-DEFINE GPB_ACCESSOR_SINGLE(NAME, TYPE, AN)
 521 //%GPB_ACCESSOR_SINGLE_FULL(NAME, TYPE, AN, )
 522 //%PDDM-DEFINE GPB_ACCESSOR_SINGLE_FULL(NAME, TYPE, AN, TisP)
 523 //%/**
 524 //% * Gets the value of a##AN NAME$L field.
 525 //% *
 526 //% * @param self  The message from which to get the field.
 527 //% * @param field The field to get.
 528 //% **/
 529 //%TYPE TisP##GPBGetMessage##NAME##Field(GPBMessage *self, GPBFieldDescriptor *field);
 530 //%
 531 //%/**
 532 //% * Sets the value of a##AN NAME$L field.
 533 //% *
 534 //% * @param self  The message into which to set the field.
 535 //% * @param field The field to set.
 536 //% * @param value The to set in the field.
 537 //% **/
 538 //%void GPBSetMessage##NAME##Field(GPBMessage *self, GPBFieldDescriptor *field, TYPE TisP##value);
 539 //%