/***
    Copyright (C) 2022 J Reece Wilson (a/k/a "Reece"). All rights reserved.

    File: ISocketDriver.hpp
    Date: 2022-8-15
    Author: Reece
***/
#pragma once

namespace Aurora::IO::Net
{
    struct NetError;

    AUKN_INTERFACE(ISocketDriver,
        AUI_METHOD(bool, OnPreestablish, (const AuSPtr<ISocket> &, pInforming)),
        
        AUI_METHOD(void, OnEstablish, ()),
        
        AUI_METHOD(void, OnStreamUpdated, ()),

        AUI_METHOD(void, OnFatalErrorReported, (const NetError&, error)),
        
        AUI_METHOD(void, OnEnd, ()),

        AUI_METHOD(void, OnFinalize, ())
    );

    /*
     * On ISocketDriver::OnEnd() versus ISocketDriver::OnFatalErrorReported() per IAsyncTransaction::HasFailed()
     * 
     *                                                     [...] various socket shutdown conditions that most applications would
     *          consider to be an unsafe shutdown are suppressed as non-fatal. Not that you can't manually query the last error, 
     *          it's just that we shouldn't be generating massive errors logs and presenting stupid warnings to the client, over so
     *          called "errors" that merely constitute somebodys mother vacuuming over an ethernet cable or a cell tower falling out of
     *          range. In my estimation, IO errors and other high level errors as presented to an application should only be that of
     *          logical errors, or that of us bailing out of an unsafe condition, or perhaps the kernel crying about IO resources. Some
     *          smart-ass networking protocol being aware of an incomplete socket shutdown isn't worth noting, unless the user has 
     *          explicit wishes to log the exact reason of socket shutdown (ie: ISocket::GetError() under ISocketDriver::OnEnd())
     * 
     *          Therefore, OnFatalErrorReported() does not report some "critical" errors in transport, unless they're actually worth noting.
     *          We simply treat them as though the socket is shutting down gracefully for ease of logging.
     *          In either case, see `ISocket::GetError()` for the exact reason of shutdown.
     */
}