Branch data     Line data    Source code

       1                 :             : /*
       2                 :             :  * Copyright 2025 Jinwoo Sung
       3                 :             :  *
       4                 :             :  * Licensed under the Apache License, Version 2.0 (the "License");
       5                 :             :  * you may not use this file except in compliance with the License.
       6                 :             :  * You may obtain a copy of the License at
       7                 :             :  *
       8                 :             :  *     http://www.apache.org/licenses/LICENSE-2.0
       9                 :             :  *
      10                 :             :  * Unless required by applicable law or agreed to in writing, software
      11                 :             :  * distributed under the License is distributed on an "AS IS" BASIS,
      12                 :             :  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      13                 :             :  * See the License for the specific language governing permissions and
      14                 :             :  * limitations under the License.
      15                 :             :  */
      16                 :             : 
      17                 :             : #pragma once
      18                 :             : 
      19                 :             : #include <functional>
      20                 :             : #include <memory>
      21                 :             : #include <vector>
      22                 :             : 
      23                 :             : #include "wirestead/base/visibility.hpp"
      24                 :             : #include "wirestead/memory/safe_span.hpp"
      25                 :             : 
      26                 :             : namespace wirestead {
      27                 :             : namespace framer {
      28                 :             : 
      29                 :             : /**
      30                 :             :  * @brief Abstract base class for message framing strategies.
      31                 :             :  *
      32                 :             :  * Handles stream-based data segmentation (e.g., separating TCP/Serial streams
      33                 :             :  * into distinct messages by delimiters or packet patterns).
      34                 :             :  */
      35                 :             : class WIRESTEAD_API IFramer {
      36                 :             :  public:
      37                 :         105 :   virtual ~IFramer() = default;
      38                 :             : 
      39                 :             :   /**
      40                 :             :    * @brief Push raw bytes into the framer's internal buffer.
      41                 :             :    *
      42                 :             :    * The framer will buffer the data and invoke the message callback
      43                 :             :    * whenever a complete message is extracted.
      44                 :             :    *
      45                 :             :    * @param data The raw data chunk to process.
      46                 :             :    */
      47                 :             :   virtual void push_bytes(memory::ConstByteSpan data) = 0;
      48                 :             : 
      49                 :             :   /**
      50                 :             :    * @brief Register a callback to be invoked when a complete message is extracted.
      51                 :             :    *
      52                 :             :    * @param cb The callback function taking a span of the message bytes.
      53                 :             :    */
      54                 :             :   using MessageCallback = std::function<void(memory::ConstByteSpan)>;
      55                 :             :   virtual void on_message(MessageCallback cb) = 0;
      56                 :             : 
      57                 :             :   /**
      58                 :             :    * @brief Reset internal state/buffer.
      59                 :             :    *
      60                 :             :    * Should be called on connection loss or when resynchronization is needed.
      61                 :             :    */
      62                 :             :   virtual void reset() = 0;
      63                 :             : };
      64                 :             : 
      65                 :             : }  // namespace framer
      66                 :             : }  // namespace wirestead