144 lines
6.0 KiB
C++
144 lines
6.0 KiB
C++
/***
|
|
Copyright (C) 2022 J Reece Wilson (a/k/a "Reece"). All rights reserved.
|
|
|
|
File: IProtocolStack.hpp
|
|
Date: 2022-8-24
|
|
Author: Reece
|
|
***/
|
|
#pragma once
|
|
|
|
namespace Aurora::IO::Protocol
|
|
{
|
|
AUE_DEFINE_VA(EProtocolWhere, eAppend, ePrepend);
|
|
|
|
struct IProtocolStack :
|
|
IProtocolBaseReader,
|
|
IProtocolBaseWriter
|
|
{
|
|
/**
|
|
* @brief
|
|
* Warning: AppendInterceptorEx is preferred
|
|
* @param pInterceptor
|
|
* @param uOutputBufferSize When 0, a hopefully not stupid default is used.
|
|
* @return
|
|
*/
|
|
virtual AuSPtr<IProtocolPiece> AddInterceptor(EProtocolWhere eWhere,
|
|
const AuSPtr<IProtocolInterceptor> &pInterceptor,
|
|
AuUInt uOutputBufferSize) = 0;
|
|
|
|
/**
|
|
* @brief
|
|
* @param pInterceptorEx
|
|
* @param uOutputBufferSize When 0, a hopefully not stupid default is used.
|
|
* @return
|
|
*/
|
|
virtual AuSPtr<IProtocolPiece> AddInterceptorEx(EProtocolWhere eWhere,
|
|
const AuSPtr<IProtocolInterceptorEx> &pInterceptorEx,
|
|
AuUInt uOutputBufferSize) = 0;
|
|
|
|
/**
|
|
* @brief defer to AppendInterceptorEx
|
|
* @param pInterceptorEx
|
|
* @param uOutputBufferSize
|
|
* @return
|
|
*/
|
|
virtual AuSPtr<IProtocolPiece> AddInterceptorDynamicBuffer(EProtocolWhere eWhere,
|
|
const AuSPtr<IProtocolInterceptorEx> &pInterceptorEx,
|
|
AuUInt uOutputBufferDefaultSize,
|
|
AuUInt uOutputBufferMaximumSize) = 0;
|
|
|
|
/**
|
|
* @brief Same as AppendInterceptor, except that DoTick will repeat until the input is fully consumed.
|
|
*
|
|
* This allows us to tick processors under our frame, followed by a retick if there is more data available to us.
|
|
* Such paradigm contrasts the default unframed/raw stream behaviour where the processor is responsible for consuming all
|
|
* available data.
|
|
* With such limitations, it's impossible to build a protocol where a piece in the middle
|
|
* 1) can/should only flush 1 frame to the following interceptor
|
|
* (this is a problem when the frame does not contain a length prefix and the next interceptor is a frame processor)
|
|
* 2) only reads a portion of pReadInByteBuffer
|
|
* (the current interceptor can only process a frame of data per tick)
|
|
*
|
|
* This function sets an internal flag that indicates re-ticks from the root single frame processor are to be expected
|
|
* in order to complete a single ::DoTick tick. With this flag enabled, multiple tick may occur as opposed to a single
|
|
* callback per ::DoTick().
|
|
* @param pInterceptorEx
|
|
* @return
|
|
*/
|
|
virtual AuSPtr<IProtocolPiece> AddSingleFrameProcessor(EProtocolWhere eWhere,
|
|
const AuSPtr<IProtocolInterceptorEx> &pInterceptorEx) = 0;
|
|
|
|
/**
|
|
* @brief Defer to AppendSingleFrameProcessor
|
|
* @param pInterceptorEx
|
|
* @param uOutputBufferSize
|
|
* @param uOutputBufferSizeMax
|
|
* @return
|
|
*/
|
|
virtual AuSPtr<IProtocolPiece> AddSingleFrameProcessorDynamicBuffer(EProtocolWhere eWhere,
|
|
const AuSPtr<IProtocolInterceptorEx> &pInterceptorEx,
|
|
AuUInt uOutputBufferDefaultSize,
|
|
AuUInt uOutputBufferMaximumSize) = 0;
|
|
|
|
/**
|
|
* @brief See: AppendSingleFrameProcessor
|
|
* @param pInterceptorEx
|
|
* @return
|
|
*/
|
|
virtual AuSPtr<IProtocolPiece> AddSingleFrameProcessorEx(EProtocolWhere eWhere,
|
|
const AuSPtr<IProtocolInterceptorEx> &pInterceptorEx,
|
|
AuUInt uOutputBufferSize) = 0;
|
|
|
|
/**
|
|
* @brief
|
|
* @param pInterceptor
|
|
* @return
|
|
*/
|
|
virtual AuSPtr<IProtocolPiece> AddEndInterceptor(const AuSPtr<IProtocolInterceptorEx> &pInterceptor) = 0;
|
|
|
|
/**
|
|
* @brief Sends one tick down the protocol stack, regardless of how much data is written into the
|
|
* next piece/interceptor, and regardless of if another read tick is required.
|
|
* @return The error state of the top-most interceptor
|
|
*/
|
|
virtual bool DoTick() = 0;
|
|
|
|
/**
|
|
* @brief
|
|
*/
|
|
virtual void Destroy() = 0;
|
|
|
|
/**
|
|
* @brief
|
|
* @return
|
|
*/
|
|
virtual AuList<AuSPtr<IProtocolPiece>> GetArrayOfInterceptors() = 0;
|
|
|
|
/**
|
|
* @brief
|
|
* @param uIndex
|
|
* @return
|
|
*/
|
|
virtual AuSPtr<IProtocolPiece> GetInterceptorAtIndex(AuUInt32 uIndex) = 0;
|
|
|
|
virtual bool IsValid() = 0;
|
|
|
|
AURT_ADD_USR_DATA;
|
|
};
|
|
|
|
/**
|
|
* @brief Allocates a new protocol stack with a buffered input stream of uLength bytes
|
|
* @param uLength
|
|
* @return
|
|
*/
|
|
AUKN_SYM AuSPtr<IProtocolStack> NewBufferedProtocolStack(AuUInt uLength);
|
|
|
|
/**
|
|
* @brief Creates a protocol stack backed by the memory of a pipe.
|
|
* @param pWork
|
|
* @return
|
|
*/
|
|
AUKN_SYM AuSPtr<IProtocolStack> NewProtocolStackFromPipe(const AuSPtr<IIOPipeWork> &pWork,
|
|
bool bAutoTick = true,
|
|
bool bKillPipeOnFirstRootLevelFalse = true);
|
|
} |