Core Concepts Overview - liuli-neko/NekoProtoTools GitHub Wiki

Welcome to the Core Concepts section of the NekoProtoTools Wiki! Understanding these fundamental ideas is key to leveraging the full power and flexibility of the library.

NekoProtoTools is designed around serialize core components that work together to simplify how you define, send, and receive structured data in your C++ applications.

The Building Blocks

Here are the main concepts you'll encounter when working with NekoProtoTools:

  1. Serializers:

    • What: Components responsible for converting your C++ objects (structs/classes) into a byte stream (like JSON, Binary) and back again.
    • How: You mark members for serialization using the NEKO_SERIALIZER macro. The library provides built-in serializers (JsonSerializer, BinarySerializer, XmlSerializer) and allows you to implement custom ones.
    • Why: Essential for storing data, sending it over the network, or interoperating with other systems.

  2. Protocol Management (IProto & ProtoFactory):

    • What: A system for managing different message types, providing polymorphism, and enabling creation by name or ID.
    • How: You declare your data structures as "protocols" using NEKO_DECLARE_PROTOCOL, associating a default serializer. You interact with them through the IProto interface and create instances using the ProtoFactory.
    • Why: Crucial for applications handling various message types dynamically, like network servers or clients processing different kinds of requests/responses.

  3. Communication Layer:

    • What: An abstraction layer built on top of the Ilias library for sending and receiving protocol messages (those declared with NEKO_DECLARE_PROTOCOL) over network streams (TCP/UDP).
    • How: Classes like ProtoStreamClient wrap underlying Ilias network objects (e.g., TcpClient) and automatically handle message framing, serialization using the protocol's default serializer, and deserialization using the ProtoFactory.
    • Why: Simplifies network code by hiding the complexities of message delineation and serialization/deserialization over a raw byte stream.

  4. JSON-RPC 2.0:

    • What: A lightweight Remote Procedure Call implementation based on the JSON-RPC 2.0 specification.
    • How: Define RPC services using structs containing RpcMethod declarations. Use JsonRpcServer to host services and JsonRpcClient to call remote methods type-safely. It uses the Ilias library for network communication.
    • Why: Provides a structured way to build client-server applications where the client can invoke functions on the server as if they were local.

How They Fit Together

  • Serializers are the foundation, providing the mechanism to convert data.
  • Protocol Management builds on serializers, adding type identity, polymorphism, and factory creation for defined message types.
  • The Communication Layer uses Protocol Management (specifically IProto and ProtoFactory) and the associated default Serializers to transmit and receive structured messages over networks.
  • JSON-RPC builds upon the Serializers to offer a high-level RPC framework.

Explore Deeper

Click on the links above to explore each concept in more detail. Understanding these individual pieces and how they interact will enable you to effectively use NekoProtoTools to build robust and efficient C++ applications.