Protocol Management - liuli-neko/NekoProtoTools GitHub Wiki

This page provides a detailed reference for the core components within the NekoProtoTools Protocol module.

Tutorial: Defining Protocol Messages

The Protocol module provides the necessary tools for managing different protocol types polymorphically.

To use the features of this module, include the following primary header(s):

#include <nekoproto/proto/proto_base.hpp>
// Add other commonly required headers for this module
// include like how to support serializer
#include <nekoproto/proto/serializer_base.hpp>
#include <nekoproto/proto/json_serializer.hpp>
#include <nekoproto/proto/types/types.hpp>

The core components of this module reside primarily in the NekoProto namespace.

• Purpose: Declares a class as a manageable protocol.
• Placement: Inside the class/struct definition.
• Syntax:

  struct MyUserData {
      // ... members ...
  
      NEKO_DECLARE_PROTOCOL(MyUserData, JsonSerializer)
  };

• Effect: Generates necessary function, make a ProtoBase class for this class, registers the type with a factory. Attach ProtoType, IProto makeProto(), static IProto emplaceProto(Args&&... args), static IProto makeProto(const MyUserData& other) for this class.

• Purpose: Declares a class as a manageable protocol.
• Type Defines:
  • ProtoType: The ProtoBase<className, Serializer>.
• Key Public Methods:
  • IProto makeProto(): Create a protocol object that references itself
  • static IProto emplaceProto(Args&&... args): Create a protocol object by Constructor.
  • static IProto makeProto(const MyUserData& other): Create a protocol object by copy constructor.
• Interaction with User Types: Users should create protocol objects through these interfaces.

• Purpose: Protocol object metadata template class
• Template Parameters:
  • template <typename ProtoT, typename SerializerT>: The protocol type and serializer type.
• Key Constructors / Creation:
  • ProtoBase(): Default constructor.
  • explicit ProtoBase(const ProtoT& /*proto*/): Constructor it by protocol object.
  • explicit ProtoBase(ProtoT&& /*proto*/): Constructor it by protocol object.
  • explicit ProtoBase(ProtoT* /*proto*/): Constructor it by protocol object pointer. will use the object reference, the pointer will not be delete.
  • ProtoBase(ProtoBase&& other) : Move constructor.
• Key Public Methods:
  • ProtoT& operator*(): get the protocol object reference.
  • ProtoT* operator->(): get the protocol object pointer.
  • const ProtoT& operator*() const: get the protocol object reference.
  • const ProtoT* operator->() const: get the protocol object pointer.
  • operator const ProtoT&() const: get the protocol object reference.
  • operator ProtoT&(): convert to the protocol object reference.
  • AbstractProto* clone(): Clone the object.
  • bool toData(std::vector<char>& buffer) const: Serialize the object to data.
  • std::vector<char> toData() const: Serialize the object to data.
  • int type() const: Get the type id of the protocol object.
  • bool fromData(const char* data, std::size_t size): Deserialize the object from data.
  • NEKO_STRING_VIEW protoName() const: Get the name of the protocol object.
  • static NEKO_STRING_VIEW name(): Get the name of the protocol object.
  • static std::vector<char> Serialize(const ProtoT& proto): Serialize ProtoT object to data.
  • static bool Serialize(const ProtoT& proto, std::vector<char>& buffer): Serialize ProtoT object to data.
  • static bool Deserialize(const char* data, std::size_t size, ProtoT& proto): Deserialize ProtoT object from data.
  • ReflectionObject* getReflectionObject(): Get the reflection object.
  • virtual void* data(): Get the ProtoT object pointer.
• Interaction with User Types: Most of the time, you will not directly touch this interface.

• Purpose: The interface for all protocols.
• Key Constructors / Creation:
  • IProto(): Default constructor.
  • IProto(AbstractProto*): Constructor, this class is constructor by ProtoBase.
  • IProto(IProto&& proto): Move constructor.
• Key Public Methods:
  • std::vector<char> toData() const: Serialize the object to data.
  • bool toData(std::vector<char>& buffer) const: Serialize the object to data.
  • bool fromData(const char* data, std::size_t size): Deserialize the object from data.
  • int type() const: Get the type id of the protocol object.
  • NEKO_STRING_VIEW protoName() const: Get the name of the protocol object.
  • IProto clone() const;: Clone the object.
  • bool operator==(std::nullptr_t) const;: Check if the object is null.
  • IProto& operator=(IProto&& proto);: Move assignment.

  • template <typename T>
    bool getField(const NEKO_STRING_VIEW& name, T* result)

    Get the field value.

  • template <typename T>
    T getField(const NEKO_STRING_VIEW& name, const T& defaultValue)

    Get the field value.

  • template <typename T>
    bool setField(const NEKO_STRING_VIEW& name, const T& value)

    Set the field value.

  • template <typename T>
    T* cast()

    Cast to the protocol object pointer.

  • template <typename T> 
    const T* cast() const

    Cast to the protocol object pointer.

  • template <typename T>
    bool operator==(T* ptr) const;

    Check if the object is equal to the protocol object.

  • template <typename T>
    IProto& operator=(const T& proto);

    Assign the protocol object.

• Purpose: The factory for creating protocol objects.
• Key Public Methods:
  • ProtoFactory(int major = 0, int minor = 0, int patch = 1): Constructor, create a factory with specified version.
  • ~ProtoFactory(): Destructor, release all the protocol objects.
  • template <typename T> void regist(const NEKO_STRING_VIEW& name): Register a protocol object.
  • void regist(const NEKO_STRING_VIEW& name, std::function<IProto()> creator): Register a protocol object with a creator function.
  • static const std::map<NEKO_STRING_VIEW, int>& protoTypeMap(): Get the protocol type map.
  • template <typename T> static int protoType(): Get the protocol type.
  • template <typename T> static int specifyProtoType(int type): Specify the protocol type.
  • template <typename T> static NEKO_STRING_VIEW protoName(): Get the protocol name.
  • IProto create(int type) const: Create a protocol object by type.
  • IProto create(const char* name) const: Create a protocol object by name.
  • uint32_t version() const: Get the version of the factory.
• Interaction with User Types: Users should create protocol objects through these interfaces.