Home | History | Annotate | only in /external/protobuf/objectivec
Up to higher level directory
NameDateSize
DevTools/06-Dec-2017
generate_well_known_types.sh06-Dec-20172K
google/06-Dec-2017
GPBArray.h06-Dec-201720K
GPBArray.m06-Dec-201774.8K
GPBArray_PackagePrivate.h06-Dec-20173.4K
GPBBootstrap.h06-Dec-20174K
GPBCodedInputStream.h06-Dec-20174.7K
GPBCodedInputStream.m06-Dec-201715.1K
GPBCodedInputStream_PackagePrivate.h06-Dec-20175.1K
GPBCodedOutputStream.h06-Dec-201714.4K
GPBCodedOutputStream.m06-Dec-201740.7K
GPBCodedOutputStream_PackagePrivate.h06-Dec-20176.1K
GPBDescriptor.h06-Dec-20175.4K
GPBDescriptor.m06-Dec-201729.5K
GPBDescriptor_PackagePrivate.h06-Dec-201711.7K
GPBDictionary.h06-Dec-201788.2K
GPBDictionary.m06-Dec-2017463K
GPBDictionary_PackagePrivate.h06-Dec-201714.6K
GPBExtensionInternals.h06-Dec-20172.4K
GPBExtensionInternals.m06-Dec-201715.3K
GPBExtensionRegistry.h06-Dec-20173.7K
GPBExtensionRegistry.m06-Dec-20174K
GPBMessage.h06-Dec-201713.6K
GPBMessage.m06-Dec-2017118.8K
GPBMessage_PackagePrivate.h06-Dec-20176.3K
GPBProtocolBuffers.h06-Dec-20172.4K
GPBProtocolBuffers.m06-Dec-20172.7K
GPBProtocolBuffers_RuntimeSupport.h06-Dec-20172K
GPBRootObject.h06-Dec-20172.1K
GPBRootObject.m06-Dec-20178.6K
GPBRootObject_PackagePrivate.h06-Dec-20172K
GPBRuntimeTypes.h06-Dec-20173.6K
GPBUnknownField.h06-Dec-20173.2K
GPBUnknownField.m06-Dec-201710.8K
GPBUnknownField_PackagePrivate.h06-Dec-20172K
GPBUnknownFieldSet.h06-Dec-20172.5K
GPBUnknownFieldSet.m06-Dec-201713.6K
GPBUnknownFieldSet_PackagePrivate.h06-Dec-20172.4K
GPBUtilities.h06-Dec-201710.9K
GPBUtilities.m06-Dec-201762.7K
GPBUtilities_PackagePrivate.h06-Dec-201713.2K
GPBWellKnownTypes.h06-Dec-20172.4K
GPBWellKnownTypes.m06-Dec-20174.2K
GPBWireFormat.h06-Dec-20172.9K
GPBWireFormat.m06-Dec-20173.4K
ProtocolBuffers_iOS.xcodeproj/06-Dec-2017
ProtocolBuffers_OSX.xcodeproj/06-Dec-2017
README.md06-Dec-20175.7K
Tests/06-Dec-2017

README.md

      1 Protocol Buffers - Google's data interchange format
      2 ===================================================
      3 
      4 [![Build Status](https://travis-ci.org/google/protobuf.svg?branch=master)](https://travis-ci.org/google/protobuf)
      5 
      6 Copyright 2008 Google Inc.
      7 
      8 This directory contains the Objective C Protocol Buffers runtime library.
      9 
     10 Requirements
     11 ------------
     12 
     13 The Objective C implementation requires:
     14 
     15 - Objective C 2.0 Runtime (32bit & 64bit iOS, 64bit OS X).
     16 - Xcode 7.0 (or later).
     17 - The library code does *not* use ARC (for performance reasons), but it all can
     18   be called from ARC code.
     19 
     20 Installation
     21 ------------
     22 
     23 The full distribution pulled from github includes the sources for both the
     24 compiler (protoc) and the runtime (this directory). To build the compiler
     25 and run the runtime tests, you can use:
     26 
     27      $ objectivec/DevTools/full_mac_build.sh
     28 
     29 This will generate the `src/protoc` binary.
     30 
     31 Building
     32 --------
     33 
     34 There are two ways to include the Runtime sources in your project:
     35 
     36 Add `objectivec/\*.h` & `objectivec/GPBProtocolBuffers.m` to your project.
     37 
     38 *or*
     39 
     40 Add `objectivec/\*.h` & `objectivec/\*.m` except for
     41 `objectivec/GPBProtocolBuffers.m` to your project.
     42 
     43 
     44 If the target is using ARC, remember to turn off ARC (`-fno-objc-arc`) for the
     45 `.m` files.
     46 
     47 The files generated by `protoc` for the `*.proto` files (`\*.pbobjc.h' and
     48 `\*.pbobjc.m`) are then also added to the target.
     49 
     50 Usage
     51 -----
     52 
     53 The objects generated for messages should work like any other Objective C
     54 object. They are mutable objects, but if you don't change them, they are safe
     55 to share between threads (similar to passing an NSMutableDictionary between
     56 threads/queues; as long as no one mutates it, things are fine).
     57 
     58 There are a few behaviors worth calling out:
     59 
     60 A property that is type NSString\* will never return nil. If the value is
     61 unset, it will return an empty string (@""). This is inpart to align things
     62 with the Protocol Buffers spec which says the default for strings is an empty
     63 string, but also so you can always safely pass them to isEqual:/compare:, etc.
     64 and have deterministic results.
     65 
     66 A property that is type NSData\* also won't return nil, it will return an empty
     67 data ([NSData data]). The reasoning is the same as for NSString not returning
     68 nil.
     69 
     70 A property that is another GPBMessage class also will not return nil. If the
     71 field wasn't already set, you will get a instance of the correct class. This
     72 instance will be a temporary instance unless you mutate it, at which point it
     73 will be attached to its parent object. We call this pattern *autocreators*.
     74 Similar to NSString and NSData properties it makes things a little safer when
     75 using them with isEqual:/etc.; but more importantly, this allows you to write
     76 code that uses Objective C's property dot notation to walk into nested objects
     77 and access and/or assign things without having to check that they are not nil
     78 and create them each step along the way. You can write this:
     79 
     80 ```
     81 - (void)updateRecord:(MyMessage *)msg {
     82   ...
     83   // Note: You don't have to check subMessage and otherMessage for nil and
     84   // alloc/init/assign them back along the way.
     85   msg.subMessage.otherMessage.lastName = @"Smith";
     86   ...
     87 }
     88 ```
     89 
     90 If you want to check if a GPBMessage property is present, there is always as
     91 `has\[NAME\]` property to go with the main property to check if it is set.
     92 
     93 A property that is of an Array or Dictionary type also provides *autocreator*
     94 behavior and will never return nil. This provides all the same benefits you
     95 see for the message properties. Again, you can write:
     96 
     97 ```
     98 - (void)updateRecord:(MyMessage *)msg {
     99   ...
    100   // Note: Just like above, you don't have to check subMessage and otherMessage
    101   // for nil and alloc/init/assign them back along the way. You also don't have
    102   // to create the siblingsArray, you can safely just append to it.
    103   [msg.subMessage.otherMessage.siblingsArray addObject:@"Pat"];
    104   ...
    105 }
    106 ```
    107 
    108 If you are inspecting a message you got from some other place (server, disk,
    109 etc), you may want to check if the Array or Dictionary has entries without
    110 causing it to be created for you. For this, there is always a `\[NAME\]_Count`
    111 property also provided that can return zero or the real count, but won't trigger
    112 the creation.
    113 
    114 For primitive type fields (ints, floats, bools, enum) in messages defined in a
    115 `.proto` file that use *proto2* syntax there are conceptual differences between
    116 having an *explicit* and *default* value. You can always get the value of the
    117 property. In the case that it hasn't been set you will get the default. In
    118 cases where you need to know whether it was set explicitly or you are just
    119 getting the default, you can use the `has\[NAME\]` property. If the value has
    120 been set, and you want to clear it, you can set the `has\[NAME\]` to `NO`.
    121 *proto3* syntax messages do away with this concept, thus the default values are
    122 never included when the message is encoded.
    123 
    124 The Objective C classes/enums can be used from Swift code.
    125 
    126 Objective C Generator Options
    127 -----------------------------
    128 
    129 **objc_class_prefix=\<prefix\>** (no default)
    130 
    131 Since Objective C uses a global namespace for all of its classes, there can
    132 be collisions. This option provides a prefix that will be added to the Enums
    133 and Objects (for messages) generated from the proto. Convention is to base
    134 the prefix on the package the proto is in.
    135 
    136 Contributing
    137 ------------
    138 
    139 Please make updates to the tests along with changes. If just changing the
    140 runtime, the Xcode projects can be used to build and run tests. If your change
    141 also requires changes to the generated code,
    142 `objectivec/DevTools/full_mac_build.sh` can be used to easily rebuild and test
    143 changes. Passing `-h` to the script will show the addition options that could
    144 be useful.
    145 
    146 Documentation
    147 -------------
    148 
    149 The complete documentation for Protocol Buffers is available via the
    150 web at:
    151 
    152     https://developers.google.com/protocol-buffers/
    153