DCCL v4
dccl::FieldCodecBase Class Referenceabstract

Provides a base class for defining DCCL field encoders / decoders. Most users who wish to define custom encoders/decoders will use the RepeatedTypedFieldCodec, TypedFieldCodec or its children (e.g. TypedFixedFieldCodec) instead of directly inheriting from this class. More...

#include <dccl/field_codec.h>

Inheritance diagram for dccl::FieldCodecBase:

Public Member Functions

Constructor, Destructor
 FieldCodecBase ()
 
virtual ~FieldCodecBase ()=default
 
Base message functions

These are called typically by Codec to start processing a new message. In this example "Foo" is a base message:

message Foo
{
int32 bar = 1;
FooBar baz = 2;
}
void base_encode (Bitset *bits, const google::protobuf::Message &msg, MessagePart part, bool strict)
 Encode this part (body or head) of the base message. More...
 
void base_size (unsigned *bit_size, const google::protobuf::Message &msg, MessagePart part)
 Calculate the size (in bits) of a part of the base message when it is encoded. More...
 
void base_decode (Bitset *bits, google::protobuf::Message *msg, MessagePart part)
 Decode part of a message. More...
 
void base_max_size (unsigned *bit_size, const google::protobuf::Descriptor *desc, MessagePart part)
 Calculate the maximum size of a message given its Descriptor alone (no data) More...
 
void base_min_size (unsigned *bit_size, const google::protobuf::Descriptor *desc, MessagePart part)
 Calculate the minimum size of a message given its Descriptor alone (no data) More...
 
void base_validate (const google::protobuf::Descriptor *desc, MessagePart part)
 Validate this part of the message to make sure all required extensions are set. More...
 
void base_info (std::ostream *os, const google::protobuf::Descriptor *desc, MessagePart part)
 Get human readable information (size of fields, etc.) about this part of the DCCL message. More...
 
void base_hash (std::size_t *hash, const google::protobuf::Descriptor *desc, MessagePart part)
 Provide a hash of the DCCL message definition to detect changes in the DCCL message. More...
 

Information Methods

std::string name () const
 the name of the codec used to identifier it in the .proto custom option extension
 
google::protobuf::FieldDescriptor::Type field_type () const
 the type exposed to the user in the original and decoded Protobuf messages More...
 
google::protobuf::FieldDescriptor::CppType wire_type () const
 the C++ type used "on the wire". This is the type visible after pre_encode and before post_decode functions are called. More...
 
const google::protobuf::FieldDescriptor * this_field () const
 Returns the FieldDescriptor (field schema meta-data) for this field. More...
 
const google::protobuf::Descriptor * this_descriptor () const
 Returns the Descriptor (message schema meta-data) for the immediate parent Message. More...
 
const google::protobuf::Messagethis_message ()
 
const google::protobuf::Messageroot_message ()
 
const google::protobuf::Descriptor * root_descriptor () const
 
internal::MessageStackDatamessage_data ()
 
const internal::MessageStackDatamessage_data () const
 
bool has_codec_group ()
 
std::string codec_group ()
 
int codec_version ()
 
MessagePart part ()
 the part of the message currently being encoded (head or body)
 
bool strict ()
 
void set_force_use_required (bool force_required=true)
 Force the codec to always use the "required" field encoding, regardless of the FieldDescriptor setting. Useful when wrapping this codec in another that handles optional and repeated fields.
 
static std::string codec_group (const google::protobuf::Descriptor *desc)
 

Field functions (primitive types and embedded messages)

class FieldCodecManagerLocal
 
struct BaseRAII
 
void field_pre_encode (dccl::any *wire_value, const dccl::any &field_value)
 Pre-encodes a non-repeated (i.e. optional or required) field by converting the FieldType representation (the Google Protobuf representation) into the WireType representation (the type used in the encoded DCCL message). This allows for type-converting codecs. More...
 
void field_pre_encode_repeated (std::vector< dccl::any > *wire_values, const std::vector< dccl::any > &field_values)
 Pre-encodes a repeated field. More...
 
void field_encode (Bitset *bits, const dccl::any &field_value, const google::protobuf::FieldDescriptor *field)
 Encode a non-repeated field. More...
 
void field_encode_repeated (Bitset *bits, const std::vector< dccl::any > &field_values, const google::protobuf::FieldDescriptor *field)
 Encode a repeated field. More...
 
void field_size (unsigned *bit_size, const dccl::any &field_value, const google::protobuf::FieldDescriptor *field)
 Calculate the size of a field. More...
 
void field_size_repeated (unsigned *bit_size, const std::vector< dccl::any > &field_values, const google::protobuf::FieldDescriptor *field)
 Calculate the size of a repeated field. More...
 
void field_decode (Bitset *bits, dccl::any *field_value, const google::protobuf::FieldDescriptor *field)
 Decode a non-repeated field. More...
 
void field_decode_repeated (Bitset *bits, std::vector< dccl::any > *field_values, const google::protobuf::FieldDescriptor *field)
 Decode a repeated field. More...
 
void field_post_decode (const dccl::any &wire_value, dccl::any *field_value)
 Post-decodes a non-repeated (i.e. optional or required) field by converting the WireType (the type used in the encoded DCCL message) representation into the FieldType representation (the Google Protobuf representation). This allows for type-converting codecs. More...
 
void field_post_decode_repeated (const std::vector< dccl::any > &wire_values, std::vector< dccl::any > *field_values)
 Post-decodes a repeated field. More...
 
void field_max_size (unsigned *bit_size, const google::protobuf::FieldDescriptor *field)
 Calculate the upper bound on this field's size (in bits) More...
 
void field_min_size (unsigned *bit_size, const google::protobuf::FieldDescriptor *field)
 Calculate the lower bound on this field's size (in bits) More...
 
void field_validate (bool *b, const google::protobuf::FieldDescriptor *field)
 Validate this field, checking that all required option extensions are set (e.g. (dccl.field).max and (dccl.field).min for arithmetic codecs) More...
 
void field_info (std::ostream *os, const google::protobuf::FieldDescriptor *field)
 Write human readable information about the field and its bounds to the provided stream. More...
 
void field_hash (std::size_t *hash, const google::protobuf::FieldDescriptor *field)
 Provide a hash for this field definition. More...
 
dccl::DCCLFieldOptions dccl_field_options () const
 Get the DCCL field option extension value for the current field. More...
 
void require (bool b, const std::string &description)
 Essentially an assertion to be used in the validate() virtual method. More...
 
DynamicConditionsdynamic_conditions (const google::protobuf::FieldDescriptor *field)
 
FieldCodecManagerLocalmanager ()
 
const FieldCodecManagerLocalmanager () const
 
virtual void set_manager (FieldCodecManagerLocal *manager)
 
bool use_required ()
 Whether to use the required or optional encoding.
 
virtual void any_encode (Bitset *bits, const dccl::any &wire_value)=0
 Virtual method used to encode. More...
 
virtual void any_decode (Bitset *bits, dccl::any *wire_value)=0
 Virtual method used to decode. More...
 
virtual void any_pre_encode (dccl::any *wire_value, const dccl::any &field_value)
 Virtual method used to pre-encode (convert from FieldType to WireType). The default implementation of this method is for when WireType == FieldType and simply copies the field_value to the wire_value. More...
 
virtual void any_post_decode (const dccl::any &wire_value, dccl::any *field_value)
 Virtual method used to post-decode (convert from WireType to FieldType). The default implementation of this method is for when WireType == FieldType and simply copies the wire_value to the field_value. More...
 
virtual unsigned any_size (const dccl::any &wire_value)=0
 Virtual method for calculating the size of a field (in bits). More...
 
virtual void validate ()
 Validate a field. Use require() inside your overloaded validate() to assert requirements or throw Exceptions directly as needed.
 
virtual std::string info ()
 Write field specific information (in addition to general information such as sizes that are automatically written by this class for all fields. More...
 
virtual std::size_t hash ()
 Generate a field specific hash to be combined with the descriptor hash.
 
virtual unsigned max_size ()=0
 Calculate maximum size of the field in bits. More...
 
virtual unsigned min_size ()=0
 Calculate minimum size of the field in bits. More...
 
virtual void any_encode_repeated (Bitset *bits, const std::vector< dccl::any > &wire_values)
 
virtual void any_decode_repeated (Bitset *repeated_bits, std::vector< dccl::any > *field_values)
 
virtual void any_pre_encode_repeated (std::vector< dccl::any > *wire_values, const std::vector< dccl::any > &field_values)
 
virtual void any_post_decode_repeated (const std::vector< dccl::any > &wire_values, std::vector< dccl::any > *field_values)
 
virtual unsigned any_size_repeated (const std::vector< dccl::any > &wire_values)
 
virtual unsigned max_size_repeated ()
 
virtual unsigned min_size_repeated ()
 
void check_repeat_settings () const
 

Detailed Description

Provides a base class for defining DCCL field encoders / decoders. Most users who wish to define custom encoders/decoders will use the RepeatedTypedFieldCodec, TypedFieldCodec or its children (e.g. TypedFixedFieldCodec) instead of directly inheriting from this class.

Definition at line 53 of file field_codec.h.

Member Function Documentation

◆ any_decode()

virtual void dccl::FieldCodecBase::any_decode ( Bitset bits,
dccl::any *  wire_value 
)
protectedpure virtual

Virtual method used to decode.

Parameters
bitsBitset containing bits to decode. This will initially contain min_size() bits. If you need more bits, call get_more_bits() with the number of bits required. This bits will be consumed from the bit pool and placed in bits.
wire_valuePlace to store decoded value (as FieldType)

◆ any_encode()

virtual void dccl::FieldCodecBase::any_encode ( Bitset bits,
const dccl::any &  wire_value 
)
protectedpure virtual

Virtual method used to encode.

Parameters
bitsBitset to store encoded bits. Bits is just the bits from the current operation (unlike base_encode() and field_encode() where bits are added to the most significant end).
wire_valueValue to encode (WireType)

◆ any_post_decode()

virtual void dccl::FieldCodecBase::any_post_decode ( const dccl::any &  wire_value,
dccl::any *  field_value 
)
inlineprotectedvirtual

Virtual method used to post-decode (convert from WireType to FieldType). The default implementation of this method is for when WireType == FieldType and simply copies the wire_value to the field_value.

Parameters
wire_valueValue to convert (WireType)
field_valueConverted value (FieldType)

Definition at line 438 of file field_codec.h.

◆ any_pre_encode()

virtual void dccl::FieldCodecBase::any_pre_encode ( dccl::any *  wire_value,
const dccl::any &  field_value 
)
inlineprotectedvirtual

Virtual method used to pre-encode (convert from FieldType to WireType). The default implementation of this method is for when WireType == FieldType and simply copies the field_value to the wire_value.

Parameters
wire_valueConverted value (WireType)
field_valueValue to convert (FieldType)

Definition at line 429 of file field_codec.h.

◆ any_size()

virtual unsigned dccl::FieldCodecBase::any_size ( const dccl::any &  wire_value)
protectedpure virtual

Virtual method for calculating the size of a field (in bits).

Parameters
wire_valueValue to calculate size of
Returns
Size of field (in bits)

◆ base_decode()

void dccl::FieldCodecBase::base_decode ( Bitset bits,
google::protobuf::Message msg,
MessagePart  part 
)

Decode part of a message.

Parameters
bitsPointer to a Bitset containing bits to decode. The least significant bits will be consumed first. Any bits not consumed will remain in bits after this method returns.
msgDCCL Message to merge the decoded result into.
partpart of the Message to decode

Definition at line 118 of file field_codec.cpp.

◆ base_encode()

void dccl::FieldCodecBase::base_encode ( Bitset bits,
const google::protobuf::Message msg,
MessagePart  part,
bool  strict 
)

Encode this part (body or head) of the base message.

Parameters
bitspointer to a Bitset where all bits will be pushed on to the most significant end.
msgDCCL Message to encode
partPart of the message to encode

Definition at line 36 of file field_codec.cpp.

◆ base_hash()

void dccl::FieldCodecBase::base_hash ( std::size_t *  hash,
const google::protobuf::Descriptor *  desc,
MessagePart  part 
)

Provide a hash of the DCCL message definition to detect changes in the DCCL message.

Parameters
hashHash value of this message part
descDescriptor to validate. Use google::protobuf::Message::GetDescriptor() or MyProtobufType::descriptor() to get this object.
partpart of the Message

Definition at line 352 of file field_codec.cpp.

◆ base_info()

void dccl::FieldCodecBase::base_info ( std::ostream *  os,
const google::protobuf::Descriptor *  desc,
MessagePart  part 
)

Get human readable information (size of fields, etc.) about this part of the DCCL message.

Parameters
osPointer to stream to store this information
descDescriptor to get information on. Use google::protobuf::Message::GetDescriptor() or MyProtobufType::descriptor() to get this object.
partthe part of the Message to act on.

Definition at line 274 of file field_codec.cpp.

◆ base_max_size()

void dccl::FieldCodecBase::base_max_size ( unsigned *  bit_size,
const google::protobuf::Descriptor *  desc,
MessagePart  part 
)

Calculate the maximum size of a message given its Descriptor alone (no data)

Parameters
bit_sizePointer to unsigned integer to store calculated maximum size in bits.
descDescriptor to calculate the maximum size of. Use google::protobuf::Message::GetDescriptor() or MyProtobufType::descriptor() to get this object.
partpart of the Message

Definition at line 190 of file field_codec.cpp.

◆ base_min_size()

void dccl::FieldCodecBase::base_min_size ( unsigned *  bit_size,
const google::protobuf::Descriptor *  desc,
MessagePart  part 
)

Calculate the minimum size of a message given its Descriptor alone (no data)

Parameters
bit_sizePointer to unsigned integer to store calculated minimum size in bits.
descDescriptor to calculate the minimum size of. Use google::protobuf::Message::GetDescriptor() or MyProtobufType::descriptor() to get this object.
partpart of the Message

Definition at line 216 of file field_codec.cpp.

◆ base_size()

void dccl::FieldCodecBase::base_size ( unsigned *  bit_size,
const google::protobuf::Message msg,
MessagePart  part 
)

Calculate the size (in bits) of a part of the base message when it is encoded.

Parameters
bit_sizePointer to unsigned integer to store the result.
msgthe DCCL Message of which to calculate the size
partpart of the Message to calculate the size of

Definition at line 85 of file field_codec.cpp.

◆ base_validate()

void dccl::FieldCodecBase::base_validate ( const google::protobuf::Descriptor *  desc,
MessagePart  part 
)

Validate this part of the message to make sure all required extensions are set.

Parameters
descDescriptor to validate. Use google::protobuf::Message::GetDescriptor() or MyProtobufType::descriptor() to get this object.
partpart of the Message

Definition at line 244 of file field_codec.cpp.

◆ dccl_field_options()

dccl::DCCLFieldOptions dccl::FieldCodecBase::dccl_field_options ( ) const
inline

Get the DCCL field option extension value for the current field.

dccl::DCCLFieldOptions is defined in acomms_option_extensions.proto

Definition at line 334 of file field_codec.h.

◆ field_decode()

void dccl::FieldCodecBase::field_decode ( Bitset bits,
dccl::any *  field_value,
const google::protobuf::FieldDescriptor *  field 
)

Decode a non-repeated field.

Parameters
bitsBits to decode. Used bits are consumed (erased) from the least significant end
field_valueLocation to store decoded value (FieldType)
fieldProtobuf descriptor to the field. Set to 0 for base message.

Definition at line 126 of file field_codec.cpp.

◆ field_decode_repeated()

void dccl::FieldCodecBase::field_decode_repeated ( Bitset bits,
std::vector< dccl::any > *  field_values,
const google::protobuf::FieldDescriptor *  field 
)

Decode a repeated field.

Parameters
bitsBits to decode. Used bits are consumed (erased) from the least significant end
field_valuesLocation to store decoded values (FieldType)
fieldProtobuf descriptor to the field. Set to 0 for base message.

Definition at line 160 of file field_codec.cpp.

◆ field_encode()

void dccl::FieldCodecBase::field_encode ( Bitset bits,
const dccl::any &  field_value,
const google::protobuf::FieldDescriptor *  field 
)

Encode a non-repeated field.

Parameters
bitsPointer to bitset to store encoded bits. Bits are added to the most significant end of bits
field_valueValue to encode (FieldType)
fieldProtobuf descriptor to the field to encode. Set to 0 for base message.

Definition at line 48 of file field_codec.cpp.

◆ field_encode_repeated()

void dccl::FieldCodecBase::field_encode_repeated ( Bitset bits,
const std::vector< dccl::any > &  field_values,
const google::protobuf::FieldDescriptor *  field 
)

Encode a repeated field.

Parameters
bitsPointer to bitset to store encoded bits. Bits are added to the most significant end of bits
field_valuesValues to encode (FieldType)
fieldProtobuf descriptor to the field. Set to 0 for base message.

Definition at line 70 of file field_codec.cpp.

◆ field_hash()

void dccl::FieldCodecBase::field_hash ( std::size_t *  hash,
const google::protobuf::FieldDescriptor *  field 
)

Provide a hash for this field definition.

Parameters
hashHash value of this field
fieldProtobuf descriptor to the field. Set to 0 for base message.

Definition at line 366 of file field_codec.cpp.

◆ field_info()

void dccl::FieldCodecBase::field_info ( std::ostream *  os,
const google::protobuf::FieldDescriptor *  field 
)

Write human readable information about the field and its bounds to the provided stream.

Parameters
osStream to write info to.
fieldProtobuf descriptor to the field. Set to 0 for base message.

Definition at line 288 of file field_codec.cpp.

◆ field_max_size()

void dccl::FieldCodecBase::field_max_size ( unsigned *  bit_size,
const google::protobuf::FieldDescriptor *  field 
)

Calculate the upper bound on this field's size (in bits)

Parameters
bit_sizeLocation to add calculated maximum bit size to. Be sure to zero bit_size if you want only the size of this field.
fieldProtobuf descriptor to the field. Set to 0 for base message.

Definition at line 205 of file field_codec.cpp.

◆ field_min_size()

void dccl::FieldCodecBase::field_min_size ( unsigned *  bit_size,
const google::protobuf::FieldDescriptor *  field 
)

Calculate the lower bound on this field's size (in bits)

Parameters
bit_sizeLocation to add calculated minimum bit size to. Be sure to zero bit_size if you want only the size of this field.
fieldProtobuf descriptor to the field. Set to 0 for base message.

Definition at line 232 of file field_codec.cpp.

◆ field_post_decode()

void dccl::FieldCodecBase::field_post_decode ( const dccl::any &  wire_value,
dccl::any *  field_value 
)
inline

Post-decodes a non-repeated (i.e. optional or required) field by converting the WireType (the type used in the encoded DCCL message) representation into the FieldType representation (the Google Protobuf representation). This allows for type-converting codecs.

Parameters
wire_valueShould be set to the desired value to translate
field_valueWill be set to the converted wire_value

Definition at line 283 of file field_codec.h.

◆ field_post_decode_repeated()

void dccl::FieldCodecBase::field_post_decode_repeated ( const std::vector< dccl::any > &  wire_values,
std::vector< dccl::any > *  field_values 
)
inline

Post-decodes a repeated field.

Parameters
wire_valuesShould be set to the desired values to translate
field_valuesWill be set to the converted wire_values

Definition at line 292 of file field_codec.h.

◆ field_pre_encode()

void dccl::FieldCodecBase::field_pre_encode ( dccl::any *  wire_value,
const dccl::any &  field_value 
)
inline

Pre-encodes a non-repeated (i.e. optional or required) field by converting the FieldType representation (the Google Protobuf representation) into the WireType representation (the type used in the encoded DCCL message). This allows for type-converting codecs.

These are called typically by DefaultMessageCodec to start processing a new field. In this example "bar" and "baz" are fields:

message Foo
{
int32 bar = 1;
FooBar baz = 2;
}
Parameters
wire_valueWill be set to the converted field_value
field_valueValue to convert to the appropriate wire_value

Definition at line 213 of file field_codec.h.

◆ field_pre_encode_repeated()

void dccl::FieldCodecBase::field_pre_encode_repeated ( std::vector< dccl::any > *  wire_values,
const std::vector< dccl::any > &  field_values 
)
inline

Pre-encodes a repeated field.

Parameters
wire_valuesShould be set to the converted field_values
field_valuesValues to convert to the appropriate wire_values

Definition at line 222 of file field_codec.h.

◆ field_size()

void dccl::FieldCodecBase::field_size ( unsigned *  bit_size,
const dccl::any &  field_value,
const google::protobuf::FieldDescriptor *  field 
)

Calculate the size of a field.

Parameters
bit_sizeLocation to add calculated bit size to. Be sure to zero bit_size if you want only the size of this field.
field_valueValue calculate size of (FieldType)
fieldProtobuf descriptor to the field. Set to 0 for base message.

Definition at line 95 of file field_codec.cpp.

◆ field_size_repeated()

void dccl::FieldCodecBase::field_size_repeated ( unsigned *  bit_size,
const std::vector< dccl::any > &  field_values,
const google::protobuf::FieldDescriptor *  field 
)

Calculate the size of a repeated field.

Parameters
bit_sizeLocation to add calculated bit size to. Be sure to zero bit_size if you want only the size of this field.
field_valuesValues to calculate size of (FieldType)
fieldProtobuf descriptor to the field. Set to 0 for base message.

Definition at line 106 of file field_codec.cpp.

◆ field_type()

google::protobuf::FieldDescriptor::Type dccl::FieldCodecBase::field_type ( ) const
inline

the type exposed to the user in the original and decoded Protobuf messages

Returns
the Google Protobuf message type. See http://code.google.com/apis/protocolbuffers/docs/reference/cpp/google.protobuf.descriptor.html#FieldDescriptor.Type.details

Definition at line 70 of file field_codec.h.

◆ field_validate()

void dccl::FieldCodecBase::field_validate ( bool b,
const google::protobuf::FieldDescriptor *  field 
)

Validate this field, checking that all required option extensions are set (e.g. (dccl.field).max and (dccl.field).min for arithmetic codecs)

Parameters
bCurrently unused (will be set to false)
fieldProtobuf descriptor to the field. Set to 0 for base message.
Exceptions
ExceptionIf field is invalid

Definition at line 258 of file field_codec.cpp.

◆ info()

std::string dccl::FieldCodecBase::info ( )
protectedvirtual

Write field specific information (in addition to general information such as sizes that are automatically written by this class for all fields.

Returns
string containing information to display.

Definition at line 420 of file field_codec.cpp.

◆ max_size()

◆ min_size()

◆ require()

void dccl::FieldCodecBase::require ( bool  b,
const std::string &  description 
)
inline

Essentially an assertion to be used in the validate() virtual method.

Parameters
bBoolean to assert (if true, execution continues, if false an exception is thrown)
descriptionDebugging description for this assertion (will be appended to the exception)
Exceptions
ExceptionThrown if !b

Definition at line 348 of file field_codec.h.

◆ this_descriptor()

const google::protobuf::Descriptor * dccl::FieldCodecBase::this_descriptor ( ) const

Returns the Descriptor (message schema meta-data) for the immediate parent Message.

for:

message Foo
{
int32 bar = 1;
FooBar baz = 2;
}

returns Descriptor for Foo if this_field() == 0 returns Descriptor for Foo if this_field() == FieldDescriptor for bar returns Descriptor for FooBar if this_field() == FieldDescriptor for baz

Definition at line 657 of file field_codec.cpp.

◆ this_field()

const google::protobuf::FieldDescriptor * dccl::FieldCodecBase::this_field ( ) const

Returns the FieldDescriptor (field schema meta-data) for this field.

Returns
FieldDescriptor for the current field or 0 if this codec is encoding the base message.

Definition at line 652 of file field_codec.cpp.

◆ wire_type()

google::protobuf::FieldDescriptor::CppType dccl::FieldCodecBase::wire_type ( ) const
inline

the C++ type used "on the wire". This is the type visible after pre_encode and before post_decode functions are called.

The wire type allows codecs to make type changes (e.g. from string to integer) before reusing another codec that knows how to encode that wire type (e.g. DefaultNumericFieldCodec)

Returns
the C++ type used to encode and decode. See http://code.google.com/apis/protocolbuffers/docs/reference/cpp/google.protobuf.descriptor.html#FieldDescriptor.CppType.details

Definition at line 75 of file field_codec.h.


The documentation for this class was generated from the following files:
dccl::int32
google::protobuf::int32 int32
a signed 32 bit integer
Definition: common.h:58