php/src/Google/Protobuf/Any.php

   1 <?php
   2 # Generated by the protocol buffer compiler.  DO NOT EDIT!
   3 # source: google/protobuf/any.proto
   4
   5 namespace Google\Protobuf;
   6
   7 use Google\Protobuf\Internal\GPBType;
   8 use Google\Protobuf\Internal\Message;
   9 use Google\Protobuf\Internal\RepeatedField;
  10 use Google\Protobuf\Internal\GPBUtil;
  11
  12 /**
  13  * `Any` contains an arbitrary serialized protocol buffer message along with a
  14  * URL that describes the type of the serialized message.
  15  * Protobuf library provides support to pack/unpack Any values in the form
  16  * of utility functions or additional generated methods of the Any type.
  17  * Example 1: Pack and unpack a message in C++.
  18  *     Foo foo = ...;
  19  *     Any any;
  20  *     any.PackFrom(foo);
  21  *     ...
  22  *     if (any.UnpackTo(&foo)) {
  23  *       ...
  24  *     }
  25  * Example 2: Pack and unpack a message in Java.
  26  *     Foo foo = ...;
  27  *     Any any = Any.pack(foo);
  28  *     ...
  29  *     if (any.is(Foo.class)) {
  30  *       foo = any.unpack(Foo.class);
  31  *     }
  32  *  Example 3: Pack and unpack a message in Python.
  33  *     foo = Foo(...)
  34  *     any = Any()
  35  *     any.Pack(foo)
  36  *     ...
  37  *     if any.Is(Foo.DESCRIPTOR):
  38  *       any.Unpack(foo)
  39  *       ...
  40  *  Example 4: Pack and unpack a message in Go
  41  *      foo := &pb.Foo{...}
  42  *      any, err := ptypes.MarshalAny(foo)
  43  *      ...
  44  *      foo := &pb.Foo{}
  45  *      if err := ptypes.UnmarshalAny(any, foo); err != nil {
  46  *        ...
  47  *      }
  48  * The pack methods provided by protobuf library will by default use
  49  * 'type.googleapis.com/full.type.name' as the type URL and the unpack
  50  * methods only use the fully qualified type name after the last '/'
  51  * in the type URL, for example "foo.bar.com/x/y.z" will yield type
  52  * name "y.z".
  53  * JSON
  54  * ====
  55  * The JSON representation of an `Any` value uses the regular
  56  * representation of the deserialized, embedded message, with an
  57  * additional field `&#64;type` which contains the type URL. Example:
  58  *     package google.profile;
  59  *     message Person {
  60  *       string first_name = 1;
  61  *       string last_name = 2;
  62  *     }
  63  *     {
  64  *       "&#64;type": "type.googleapis.com/google.profile.Person",
  65  *       "firstName": <string>,
  66  *       "lastName": <string>
  67  *     }
  68  * If the embedded message type is well-known and has a custom JSON
  69  * representation, that representation will be embedded adding a field
  70  * `value` which holds the custom JSON in addition to the `&#64;type`
  71  * field. Example (for message [google.protobuf.Duration][]):
  72  *     {
  73  *       "&#64;type": "type.googleapis.com/google.protobuf.Duration",
  74  *       "value": "1.212s"
  75  *     }
  76  *
  77  * Generated from protobuf message <code>google.protobuf.Any</code>
  78  */
  79 class Any extends \Google\Protobuf\Internal\Message
  80 {
  81     /**
  82      * A URL/resource name that uniquely identifies the type of the serialized
  83      * protocol buffer message. The last segment of the URL's path must represent
  84      * the fully qualified name of the type (as in
  85      * `path/google.protobuf.Duration`). The name should be in a canonical form
  86      * (e.g., leading "." is not accepted).
  87      * In practice, teams usually precompile into the binary all types that they
  88      * expect it to use in the context of Any. However, for URLs which use the
  89      * scheme `http`, `https`, or no scheme, one can optionally set up a type
  90      * server that maps type URLs to message definitions as follows:
  91      * * If no scheme is provided, `https` is assumed.
  92      * * An HTTP GET on the URL must yield a [google.protobuf.Type][]
  93      *   value in binary format, or produce an error.
  94      * * Applications are allowed to cache lookup results based on the
  95      *   URL, or have them precompiled into a binary to avoid any
  96      *   lookup. Therefore, binary compatibility needs to be preserved
  97      *   on changes to types. (Use versioned type names to manage
  98      *   breaking changes.)
  99      * Note: this functionality is not currently available in the official
 100      * protobuf release, and it is not used for type URLs beginning with
 101      * type.googleapis.com.
 102      * Schemes other than `http`, `https` (or the empty scheme) might be
 103      * used with implementation specific semantics.
 104      *
 105      * Generated from protobuf field <code>string type_url = 1;</code>
 106      */
 107     private $type_url = '';
 108     /**
 109      * Must be a valid serialized protocol buffer of the above specified type.
 110      *
 111      * Generated from protobuf field <code>bytes value = 2;</code>
 112      */
 113     private $value = '';
 114
 115     const TYPE_URL_PREFIX = 'type.googleapis.com/';
 116
 117     /**
 118      * Constructor.
 119      *
 120      * @param array $data {
 121      *     Optional. Data for populating the Message object.
 122      *
 123      *     @type string $type_url
 124      *           A URL/resource name that uniquely identifies the type of the serialized
 125      *           protocol buffer message. The last segment of the URL's path must represent
 126      *           the fully qualified name of the type (as in
 127      *           `path/google.protobuf.Duration`). The name should be in a canonical form
 128      *           (e.g., leading "." is not accepted).
 129      *           In practice, teams usually precompile into the binary all types that they
 130      *           expect it to use in the context of Any. However, for URLs which use the
 131      *           scheme `http`, `https`, or no scheme, one can optionally set up a type
 132      *           server that maps type URLs to message definitions as follows:
 133      *           * If no scheme is provided, `https` is assumed.
 134      *           * An HTTP GET on the URL must yield a [google.protobuf.Type][]
 135      *             value in binary format, or produce an error.
 136      *           * Applications are allowed to cache lookup results based on the
 137      *             URL, or have them precompiled into a binary to avoid any
 138      *             lookup. Therefore, binary compatibility needs to be preserved
 139      *             on changes to types. (Use versioned type names to manage
 140      *             breaking changes.)
 141      *           Note: this functionality is not currently available in the official
 142      *           protobuf release, and it is not used for type URLs beginning with
 143      *           type.googleapis.com.
 144      *           Schemes other than `http`, `https` (or the empty scheme) might be
 145      *           used with implementation specific semantics.
 146      *     @type string $value
 147      *           Must be a valid serialized protocol buffer of the above specified type.
 148      * }
 149      */
 150     public function __construct($data = NULL) {
 151         \GPBMetadata\Google\Protobuf\Any::initOnce();
 152         parent::__construct($data);
 153     }
 154
 155     /**
 156      * A URL/resource name that uniquely identifies the type of the serialized
 157      * protocol buffer message. The last segment of the URL's path must represent
 158      * the fully qualified name of the type (as in
 159      * `path/google.protobuf.Duration`). The name should be in a canonical form
 160      * (e.g., leading "." is not accepted).
 161      * In practice, teams usually precompile into the binary all types that they
 162      * expect it to use in the context of Any. However, for URLs which use the
 163      * scheme `http`, `https`, or no scheme, one can optionally set up a type
 164      * server that maps type URLs to message definitions as follows:
 165      * * If no scheme is provided, `https` is assumed.
 166      * * An HTTP GET on the URL must yield a [google.protobuf.Type][]
 167      *   value in binary format, or produce an error.
 168      * * Applications are allowed to cache lookup results based on the
 169      *   URL, or have them precompiled into a binary to avoid any
 170      *   lookup. Therefore, binary compatibility needs to be preserved
 171      *   on changes to types. (Use versioned type names to manage
 172      *   breaking changes.)
 173      * Note: this functionality is not currently available in the official
 174      * protobuf release, and it is not used for type URLs beginning with
 175      * type.googleapis.com.
 176      * Schemes other than `http`, `https` (or the empty scheme) might be
 177      * used with implementation specific semantics.
 178      *
 179      * Generated from protobuf field <code>string type_url = 1;</code>
 180      * @return string
 181      */
 182     public function getTypeUrl()
 183     {
 184         return $this->type_url;
 185     }
 186
 187     /**
 188      * A URL/resource name that uniquely identifies the type of the serialized
 189      * protocol buffer message. The last segment of the URL's path must represent
 190      * the fully qualified name of the type (as in
 191      * `path/google.protobuf.Duration`). The name should be in a canonical form
 192      * (e.g., leading "." is not accepted).
 193      * In practice, teams usually precompile into the binary all types that they
 194      * expect it to use in the context of Any. However, for URLs which use the
 195      * scheme `http`, `https`, or no scheme, one can optionally set up a type
 196      * server that maps type URLs to message definitions as follows:
 197      * * If no scheme is provided, `https` is assumed.
 198      * * An HTTP GET on the URL must yield a [google.protobuf.Type][]
 199      *   value in binary format, or produce an error.
 200      * * Applications are allowed to cache lookup results based on the
 201      *   URL, or have them precompiled into a binary to avoid any
 202      *   lookup. Therefore, binary compatibility needs to be preserved
 203      *   on changes to types. (Use versioned type names to manage
 204      *   breaking changes.)
 205      * Note: this functionality is not currently available in the official
 206      * protobuf release, and it is not used for type URLs beginning with
 207      * type.googleapis.com.
 208      * Schemes other than `http`, `https` (or the empty scheme) might be
 209      * used with implementation specific semantics.
 210      *
 211      * Generated from protobuf field <code>string type_url = 1;</code>
 212      * @param string $var
 213      * @return $this
 214      */
 215     public function setTypeUrl($var)
 216     {
 217         GPBUtil::checkString($var, True);
 218         $this->type_url = $var;
 219
 220         return $this;
 221     }
 222
 223     /**
 224      * Must be a valid serialized protocol buffer of the above specified type.
 225      *
 226      * Generated from protobuf field <code>bytes value = 2;</code>
 227      * @return string
 228      */
 229     public function getValue()
 230     {
 231         return $this->value;
 232     }
 233
 234     /**
 235      * Must be a valid serialized protocol buffer of the above specified type.
 236      *
 237      * Generated from protobuf field <code>bytes value = 2;</code>
 238      * @param string $var
 239      * @return $this
 240      */
 241     public function setValue($var)
 242     {
 243         GPBUtil::checkString($var, False);
 244         $this->value = $var;
 245
 246         return $this;
 247     }
 248
 249     /**
 250      * This method will try to resolve the type_url in Any message to get the
 251      * targeted message type. If failed, an error will be thrown. Otherwise,
 252      * the method will create a message of the targeted type and fill it with
 253      * the decoded value in Any.
 254      * @return unpacked message
 255      * @throws \Exception Type url needs to be type.googleapis.com/fully-qulified.
 256      * @throws \Exception Class hasn't been added to descriptor pool.
 257      * @throws \Exception cannot decode data in value field.
 258      */
 259     public function unpack()
 260     {
 261         // Get fully qualifed name from type url.
 262         $url_prifix_len = strlen(GPBUtil::TYPE_URL_PREFIX);
 263         if (substr($this->type_url, 0, $url_prifix_len) !=
 264                 GPBUtil::TYPE_URL_PREFIX) {
 265             throw new \Exception(
 266                 "Type url needs to be type.googleapis.com/fully-qulified");
 267         }
 268         $fully_qualifed_name =
 269             substr($this->type_url, $url_prifix_len);
 270
 271         // Create message according to fully qualified name.
 272         $pool = \Google\Protobuf\Internal\DescriptorPool::getGeneratedPool();
 273         $desc = $pool->getDescriptorByProtoName( ".".$fully_qualifed_name);
 274         if (is_null($desc)) {
 275             throw new \Exception("Class ".$fully_qualifed_name
 276                                      ." hasn't been added to descriptor pool");
 277         }
 278         $klass = $desc->getClass();
 279         $msg = new $klass();
 280
 281         // Merge data into message.
 282         $msg->mergeFromString($this->value);
 283         return $msg;
 284     }
 285
 286     /**
 287      * The type_url will be created according to the given message’s type and
 288      * the value is encoded data from the given message..
 289      * @param message: A proto message.
 290      */
 291     public function pack($msg)
 292     {
 293         if (!$msg instanceof Message) {
 294             trigger_error("Given parameter is not a message instance.",
 295                           E_USER_ERROR);
 296             return;
 297         }
 298
 299         // Set value using serialzed message.
 300         $this->value = $msg->serializeToString();
 301
 302         // Set type url.
 303         $pool = \Google\Protobuf\Internal\DescriptorPool::getGeneratedPool();
 304         $desc = $pool->getDescriptorByClassName(get_class($msg));
 305         $fully_qualifed_name = $desc->getFullName();
 306         $this->type_url = GPBUtil::TYPE_URL_PREFIX.substr(
 307             $fully_qualifed_name, 1, strlen($fully_qualifed_name));
 308     }
 309
 310     /**
 311      * This method returns whether the type_url in any_message is corresponded
 312      * to the given class.
 313      * @param klass: The fully qualified PHP class name of a proto message type.
 314      */
 315     public function is($klass)
 316     {
 317         $pool = \Google\Protobuf\Internal\DescriptorPool::getGeneratedPool();
 318         $desc = $pool->getDescriptorByClassName($klass);
 319         $fully_qualifed_name = $desc->getFullName();
 320         $type_url = GPBUtil::TYPE_URL_PREFIX.substr(
 321             $fully_qualifed_name, 1, strlen($fully_qualifed_name));
 322         return $this->type_url === $type_url;
 323     }
 324 }
 325