GPBUtilities.h 17 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551
  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. #import <Foundation/Foundation.h>
  31. #import "GPBArray.h"
  32. #import "GPBMessage.h"
  33. #import "GPBRuntimeTypes.h"
  34. @class GPBOneofDescriptor;
  35. CF_EXTERN_C_BEGIN
  36. NS_ASSUME_NONNULL_BEGIN
  37. /**
  38. * Generates a string that should be a valid "TextFormat" for the C++ version
  39. * of Protocol Buffers.
  40. *
  41. * @param message The message to generate from.
  42. * @param lineIndent A string to use as the prefix for all lines generated. Can
  43. * be nil if no extra indent is needed.
  44. *
  45. * @return An NSString with the TextFormat of the message.
  46. **/
  47. NSString *GPBTextFormatForMessage(GPBMessage *message,
  48. NSString * __nullable lineIndent);
  49. /**
  50. * Generates a string that should be a valid "TextFormat" for the C++ version
  51. * of Protocol Buffers.
  52. *
  53. * @param unknownSet The unknown field set to generate from.
  54. * @param lineIndent A string to use as the prefix for all lines generated. Can
  55. * be nil if no extra indent is needed.
  56. *
  57. * @return An NSString with the TextFormat of the unknown field set.
  58. **/
  59. NSString *GPBTextFormatForUnknownFieldSet(GPBUnknownFieldSet * __nullable unknownSet,
  60. NSString * __nullable lineIndent);
  61. /**
  62. * Checks if the given field number is set on a message.
  63. *
  64. * @param self The message to check.
  65. * @param fieldNumber The field number to check.
  66. *
  67. * @return YES if the field number is set on the given message.
  68. **/
  69. BOOL GPBMessageHasFieldNumberSet(GPBMessage *self, uint32_t fieldNumber);
  70. /**
  71. * Checks if the given field is set on a message.
  72. *
  73. * @param self The message to check.
  74. * @param field The field to check.
  75. *
  76. * @return YES if the field is set on the given message.
  77. **/
  78. BOOL GPBMessageHasFieldSet(GPBMessage *self, GPBFieldDescriptor *field);
  79. /**
  80. * Clears the given field for the given message.
  81. *
  82. * @param self The message for which to clear the field.
  83. * @param field The field to clear.
  84. **/
  85. void GPBClearMessageField(GPBMessage *self, GPBFieldDescriptor *field);
  86. /**
  87. * Clears the given oneof field for the given message.
  88. *
  89. * @param self The message for which to clear the field.
  90. * @param oneof The oneof to clear.
  91. **/
  92. void GPBClearOneof(GPBMessage *self, GPBOneofDescriptor *oneof);
  93. //%PDDM-EXPAND GPB_ACCESSORS()
  94. // This block of code is generated, do not edit it directly.
  95. // clang-format off
  96. //
  97. // Get/Set a given field from/to a message.
  98. //
  99. // Single Fields
  100. /**
  101. * Gets the value of a bytes field.
  102. *
  103. * @param self The message from which to get the field.
  104. * @param field The field to get.
  105. **/
  106. NSData *GPBGetMessageBytesField(GPBMessage *self, GPBFieldDescriptor *field);
  107. /**
  108. * Sets the value of a bytes field.
  109. *
  110. * @param self The message into which to set the field.
  111. * @param field The field to set.
  112. * @param value The to set in the field.
  113. **/
  114. void GPBSetMessageBytesField(GPBMessage *self, GPBFieldDescriptor *field, NSData *value);
  115. /**
  116. * Gets the value of a string field.
  117. *
  118. * @param self The message from which to get the field.
  119. * @param field The field to get.
  120. **/
  121. NSString *GPBGetMessageStringField(GPBMessage *self, GPBFieldDescriptor *field);
  122. /**
  123. * Sets the value of a string field.
  124. *
  125. * @param self The message into which to set the field.
  126. * @param field The field to set.
  127. * @param value The to set in the field.
  128. **/
  129. void GPBSetMessageStringField(GPBMessage *self, GPBFieldDescriptor *field, NSString *value);
  130. /**
  131. * Gets the value of a message field.
  132. *
  133. * @param self The message from which to get the field.
  134. * @param field The field to get.
  135. **/
  136. GPBMessage *GPBGetMessageMessageField(GPBMessage *self, GPBFieldDescriptor *field);
  137. /**
  138. * Sets the value of a message field.
  139. *
  140. * @param self The message into which to set the field.
  141. * @param field The field to set.
  142. * @param value The to set in the field.
  143. **/
  144. void GPBSetMessageMessageField(GPBMessage *self, GPBFieldDescriptor *field, GPBMessage *value);
  145. /**
  146. * Gets the value of a group field.
  147. *
  148. * @param self The message from which to get the field.
  149. * @param field The field to get.
  150. **/
  151. GPBMessage *GPBGetMessageGroupField(GPBMessage *self, GPBFieldDescriptor *field);
  152. /**
  153. * Sets the value of a group field.
  154. *
  155. * @param self The message into which to set the field.
  156. * @param field The field to set.
  157. * @param value The to set in the field.
  158. **/
  159. void GPBSetMessageGroupField(GPBMessage *self, GPBFieldDescriptor *field, GPBMessage *value);
  160. /**
  161. * Gets the value of a bool field.
  162. *
  163. * @param self The message from which to get the field.
  164. * @param field The field to get.
  165. **/
  166. BOOL GPBGetMessageBoolField(GPBMessage *self, GPBFieldDescriptor *field);
  167. /**
  168. * Sets the value of a bool field.
  169. *
  170. * @param self The message into which to set the field.
  171. * @param field The field to set.
  172. * @param value The to set in the field.
  173. **/
  174. void GPBSetMessageBoolField(GPBMessage *self, GPBFieldDescriptor *field, BOOL value);
  175. /**
  176. * Gets the value of an int32 field.
  177. *
  178. * @param self The message from which to get the field.
  179. * @param field The field to get.
  180. **/
  181. int32_t GPBGetMessageInt32Field(GPBMessage *self, GPBFieldDescriptor *field);
  182. /**
  183. * Sets the value of an int32 field.
  184. *
  185. * @param self The message into which to set the field.
  186. * @param field The field to set.
  187. * @param value The to set in the field.
  188. **/
  189. void GPBSetMessageInt32Field(GPBMessage *self, GPBFieldDescriptor *field, int32_t value);
  190. /**
  191. * Gets the value of an uint32 field.
  192. *
  193. * @param self The message from which to get the field.
  194. * @param field The field to get.
  195. **/
  196. uint32_t GPBGetMessageUInt32Field(GPBMessage *self, GPBFieldDescriptor *field);
  197. /**
  198. * Sets the value of an uint32 field.
  199. *
  200. * @param self The message into which to set the field.
  201. * @param field The field to set.
  202. * @param value The to set in the field.
  203. **/
  204. void GPBSetMessageUInt32Field(GPBMessage *self, GPBFieldDescriptor *field, uint32_t value);
  205. /**
  206. * Gets the value of an int64 field.
  207. *
  208. * @param self The message from which to get the field.
  209. * @param field The field to get.
  210. **/
  211. int64_t GPBGetMessageInt64Field(GPBMessage *self, GPBFieldDescriptor *field);
  212. /**
  213. * Sets the value of an int64 field.
  214. *
  215. * @param self The message into which to set the field.
  216. * @param field The field to set.
  217. * @param value The to set in the field.
  218. **/
  219. void GPBSetMessageInt64Field(GPBMessage *self, GPBFieldDescriptor *field, int64_t value);
  220. /**
  221. * Gets the value of an uint64 field.
  222. *
  223. * @param self The message from which to get the field.
  224. * @param field The field to get.
  225. **/
  226. uint64_t GPBGetMessageUInt64Field(GPBMessage *self, GPBFieldDescriptor *field);
  227. /**
  228. * Sets the value of an uint64 field.
  229. *
  230. * @param self The message into which to set the field.
  231. * @param field The field to set.
  232. * @param value The to set in the field.
  233. **/
  234. void GPBSetMessageUInt64Field(GPBMessage *self, GPBFieldDescriptor *field, uint64_t value);
  235. /**
  236. * Gets the value of a float field.
  237. *
  238. * @param self The message from which to get the field.
  239. * @param field The field to get.
  240. **/
  241. float GPBGetMessageFloatField(GPBMessage *self, GPBFieldDescriptor *field);
  242. /**
  243. * Sets the value of a float field.
  244. *
  245. * @param self The message into which to set the field.
  246. * @param field The field to set.
  247. * @param value The to set in the field.
  248. **/
  249. void GPBSetMessageFloatField(GPBMessage *self, GPBFieldDescriptor *field, float value);
  250. /**
  251. * Gets the value of a double field.
  252. *
  253. * @param self The message from which to get the field.
  254. * @param field The field to get.
  255. **/
  256. double GPBGetMessageDoubleField(GPBMessage *self, GPBFieldDescriptor *field);
  257. /**
  258. * Sets the value of a double field.
  259. *
  260. * @param self The message into which to set the field.
  261. * @param field The field to set.
  262. * @param value The to set in the field.
  263. **/
  264. void GPBSetMessageDoubleField(GPBMessage *self, GPBFieldDescriptor *field, double value);
  265. /**
  266. * Gets the given enum field of a message. For proto3, if the value isn't a
  267. * member of the enum, @c kGPBUnrecognizedEnumeratorValue will be returned.
  268. * GPBGetMessageRawEnumField will bypass the check and return whatever value
  269. * was set.
  270. *
  271. * @param self The message from which to get the field.
  272. * @param field The field to get.
  273. *
  274. * @return The enum value for the given field.
  275. **/
  276. int32_t GPBGetMessageEnumField(GPBMessage *self, GPBFieldDescriptor *field);
  277. /**
  278. * Set the given enum field of a message. You can only set values that are
  279. * members of the enum.
  280. *
  281. * @param self The message into which to set the field.
  282. * @param field The field to set.
  283. * @param value The enum value to set in the field.
  284. **/
  285. void GPBSetMessageEnumField(GPBMessage *self,
  286. GPBFieldDescriptor *field,
  287. int32_t value);
  288. /**
  289. * Get the given enum field of a message. No check is done to ensure the value
  290. * was defined in the enum.
  291. *
  292. * @param self The message from which to get the field.
  293. * @param field The field to get.
  294. *
  295. * @return The raw enum value for the given field.
  296. **/
  297. int32_t GPBGetMessageRawEnumField(GPBMessage *self, GPBFieldDescriptor *field);
  298. /**
  299. * Set the given enum field of a message. You can set the value to anything,
  300. * even a value that is not a member of the enum.
  301. *
  302. * @param self The message into which to set the field.
  303. * @param field The field to set.
  304. * @param value The raw enum value to set in the field.
  305. **/
  306. void GPBSetMessageRawEnumField(GPBMessage *self,
  307. GPBFieldDescriptor *field,
  308. int32_t value);
  309. // Repeated Fields
  310. /**
  311. * Gets the value of a repeated field.
  312. *
  313. * @param self The message from which to get the field.
  314. * @param field The repeated field to get.
  315. *
  316. * @return A GPB*Array or an NSMutableArray based on the field's type.
  317. **/
  318. id GPBGetMessageRepeatedField(GPBMessage *self, GPBFieldDescriptor *field);
  319. /**
  320. * Sets the value of a repeated field.
  321. *
  322. * @param self The message into which to set the field.
  323. * @param field The field to set.
  324. * @param array A GPB*Array or NSMutableArray based on the field's type.
  325. **/
  326. void GPBSetMessageRepeatedField(GPBMessage *self,
  327. GPBFieldDescriptor *field,
  328. id array);
  329. // Map Fields
  330. /**
  331. * Gets the value of a map<> field.
  332. *
  333. * @param self The message from which to get the field.
  334. * @param field The repeated field to get.
  335. *
  336. * @return A GPB*Dictionary or NSMutableDictionary based on the field's type.
  337. **/
  338. id GPBGetMessageMapField(GPBMessage *self, GPBFieldDescriptor *field);
  339. /**
  340. * Sets the value of a map<> field.
  341. *
  342. * @param self The message into which to set the field.
  343. * @param field The field to set.
  344. * @param dictionary A GPB*Dictionary or NSMutableDictionary based on the
  345. * field's type.
  346. **/
  347. void GPBSetMessageMapField(GPBMessage *self,
  348. GPBFieldDescriptor *field,
  349. id dictionary);
  350. // clang-format on
  351. //%PDDM-EXPAND-END GPB_ACCESSORS()
  352. /**
  353. * Returns an empty NSData to assign to byte fields when you wish to assign them
  354. * to empty. Prevents allocating a lot of little [NSData data] objects.
  355. **/
  356. NSData *GPBEmptyNSData(void) __attribute__((pure));
  357. /**
  358. * Drops the `unknownFields` from the given message and from all sub message.
  359. **/
  360. void GPBMessageDropUnknownFieldsRecursively(GPBMessage *message);
  361. NS_ASSUME_NONNULL_END
  362. CF_EXTERN_C_END
  363. //%PDDM-DEFINE GPB_ACCESSORS()
  364. //%
  365. //%//
  366. //%// Get/Set a given field from/to a message.
  367. //%//
  368. //%
  369. //%// Single Fields
  370. //%
  371. //%GPB_ACCESSOR_SINGLE_FULL(Bytes, NSData, , *)
  372. //%GPB_ACCESSOR_SINGLE_FULL(String, NSString, , *)
  373. //%GPB_ACCESSOR_SINGLE_FULL(Message, GPBMessage, , *)
  374. //%GPB_ACCESSOR_SINGLE_FULL(Group, GPBMessage, , *)
  375. //%GPB_ACCESSOR_SINGLE(Bool, BOOL, )
  376. //%GPB_ACCESSOR_SINGLE(Int32, int32_t, n)
  377. //%GPB_ACCESSOR_SINGLE(UInt32, uint32_t, n)
  378. //%GPB_ACCESSOR_SINGLE(Int64, int64_t, n)
  379. //%GPB_ACCESSOR_SINGLE(UInt64, uint64_t, n)
  380. //%GPB_ACCESSOR_SINGLE(Float, float, )
  381. //%GPB_ACCESSOR_SINGLE(Double, double, )
  382. //%/**
  383. //% * Gets the given enum field of a message. For proto3, if the value isn't a
  384. //% * member of the enum, @c kGPBUnrecognizedEnumeratorValue will be returned.
  385. //% * GPBGetMessageRawEnumField will bypass the check and return whatever value
  386. //% * was set.
  387. //% *
  388. //% * @param self The message from which to get the field.
  389. //% * @param field The field to get.
  390. //% *
  391. //% * @return The enum value for the given field.
  392. //% **/
  393. //%int32_t GPBGetMessageEnumField(GPBMessage *self, GPBFieldDescriptor *field);
  394. //%
  395. //%/**
  396. //% * Set the given enum field of a message. You can only set values that are
  397. //% * members of the enum.
  398. //% *
  399. //% * @param self The message into which to set the field.
  400. //% * @param field The field to set.
  401. //% * @param value The enum value to set in the field.
  402. //% **/
  403. //%void GPBSetMessageEnumField(GPBMessage *self,
  404. //% GPBFieldDescriptor *field,
  405. //% int32_t value);
  406. //%
  407. //%/**
  408. //% * Get the given enum field of a message. No check is done to ensure the value
  409. //% * was defined in the enum.
  410. //% *
  411. //% * @param self The message from which to get the field.
  412. //% * @param field The field to get.
  413. //% *
  414. //% * @return The raw enum value for the given field.
  415. //% **/
  416. //%int32_t GPBGetMessageRawEnumField(GPBMessage *self, GPBFieldDescriptor *field);
  417. //%
  418. //%/**
  419. //% * Set the given enum field of a message. You can set the value to anything,
  420. //% * even a value that is not a member of the enum.
  421. //% *
  422. //% * @param self The message into which to set the field.
  423. //% * @param field The field to set.
  424. //% * @param value The raw enum value to set in the field.
  425. //% **/
  426. //%void GPBSetMessageRawEnumField(GPBMessage *self,
  427. //% GPBFieldDescriptor *field,
  428. //% int32_t value);
  429. //%
  430. //%// Repeated Fields
  431. //%
  432. //%/**
  433. //% * Gets the value of a repeated field.
  434. //% *
  435. //% * @param self The message from which to get the field.
  436. //% * @param field The repeated field to get.
  437. //% *
  438. //% * @return A GPB*Array or an NSMutableArray based on the field's type.
  439. //% **/
  440. //%id GPBGetMessageRepeatedField(GPBMessage *self, GPBFieldDescriptor *field);
  441. //%
  442. //%/**
  443. //% * Sets the value of a repeated field.
  444. //% *
  445. //% * @param self The message into which to set the field.
  446. //% * @param field The field to set.
  447. //% * @param array A GPB*Array or NSMutableArray based on the field's type.
  448. //% **/
  449. //%void GPBSetMessageRepeatedField(GPBMessage *self,
  450. //% GPBFieldDescriptor *field,
  451. //% id array);
  452. //%
  453. //%// Map Fields
  454. //%
  455. //%/**
  456. //% * Gets the value of a map<> field.
  457. //% *
  458. //% * @param self The message from which to get the field.
  459. //% * @param field The repeated field to get.
  460. //% *
  461. //% * @return A GPB*Dictionary or NSMutableDictionary based on the field's type.
  462. //% **/
  463. //%id GPBGetMessageMapField(GPBMessage *self, GPBFieldDescriptor *field);
  464. //%
  465. //%/**
  466. //% * Sets the value of a map<> field.
  467. //% *
  468. //% * @param self The message into which to set the field.
  469. //% * @param field The field to set.
  470. //% * @param dictionary A GPB*Dictionary or NSMutableDictionary based on the
  471. //% * field's type.
  472. //% **/
  473. //%void GPBSetMessageMapField(GPBMessage *self,
  474. //% GPBFieldDescriptor *field,
  475. //% id dictionary);
  476. //%
  477. //%PDDM-DEFINE GPB_ACCESSOR_SINGLE(NAME, TYPE, AN)
  478. //%GPB_ACCESSOR_SINGLE_FULL(NAME, TYPE, AN, )
  479. //%PDDM-DEFINE GPB_ACCESSOR_SINGLE_FULL(NAME, TYPE, AN, TisP)
  480. //%/**
  481. //% * Gets the value of a##AN NAME$L field.
  482. //% *
  483. //% * @param self The message from which to get the field.
  484. //% * @param field The field to get.
  485. //% **/
  486. //%TYPE TisP##GPBGetMessage##NAME##Field(GPBMessage *self, GPBFieldDescriptor *field);
  487. //%
  488. //%/**
  489. //% * Sets the value of a##AN NAME$L field.
  490. //% *
  491. //% * @param self The message into which to set the field.
  492. //% * @param field The field to set.
  493. //% * @param value The to set in the field.
  494. //% **/
  495. //%void GPBSetMessage##NAME##Field(GPBMessage *self, GPBFieldDescriptor *field, TYPE TisP##value);
  496. //%