ProtobufInstantiate

Description:	Instantiates a message using default values. This is useful where a non-trivial message type is used as it allows the script code developer to create an instance of a message suitable for encoding without re-defining the message structure.
Returns:
Usage:	Script Only.
Function Groups:	Protobuf
Related to:	ProtobufDecode | ProtobufEncode | ProtobufParse
Format:	ProtobufInstantiate(ProtobufHandle, MessageTypeName[, optionalsAsInvalid])
Parameters:

ProtobufHandle

A Protobuf handle returned from ProtobufParse.

MessageTypeName

The message type to use for decoding. This is the full name, that is, if the .proto file includes a package name "com.trihedral.protobufexample" and the message name is "AMessage", this would be "com.trihedral.protobufexample.AMessage". For nested messages this also includes all ancestor messages

OptionalsAsInvalid

Optional Boolean. Defaults to FALSE when unspecified or invalid. When TRUE, fields in a Protobuf specification file that are defined as optional are not given a default value when instantiated.

Comments:

Generates a VTScada data structure based on the loaded proto file, so that the structure can be populated with data from script code before being used in a call to ProtobufEncode.

Related Information:

Protobuf Support

Example:

Given a Protobuf specification file held in "example.proto" in a sub-folder protobuf of an application:

syntax = "proto2";

package com.trihedral.protobuf.example;

message VersionInformation {
  required string name    = 1;
  required double version = 2;
}

The following code parses, instantiates, encodes and then decodes a message:

<
{============================= ProtobufExample ===============================}
{ Demonstration of parsing, encoding, decoding and instantiating Protobuf    }
{ messages.                                                                   }
{=============================================================================}
ProtobufExample
[
  Protected ProtobufHandle;
  Protected MessageInstance;
  Protected EncodedMessage;
  Protected DecodedMessage;
]

ProtobufExample [
  If TRUE;
  [
    ProtobufHandle = ProtobufParse(Concat(Layer.GetWCPath(), "protobuf\example.proto"));
    MessageInstance = ProtobufInstantiate(ProtobufHandle, "com.trihedral.protobuf.example.VersionInformation");

    MessageInstance.name = "VTScada";
    MessageInstance.version = 12;

    EncodedMessage = ProtobufEncode(ProtobufHandle, "com.trihedral.protobuf.example.VersionInformation", MessageInstance);

    DecodedMessage = ProtobufDecode(ProtobufHandle, "com.trihedral.protobuf.example.VersionInformation", EncodedMessage);

    Return();
  ]
]

{ End of ProtobufExample }
>