//  --------------------------------------------------------------------------
//  Module Name: APIDispatcher.h
//
//  Copyright (c) 1999-2000, Microsoft Corporation
//
//  A class that handles API requests in the server on a separate thread. Each
//  thread is dedicated to respond to a single client. This is acceptable for
//  a lightweight server.
//
//  History:    1999-11-07  vtan        created
//              2000-08-25  vtan        moved from Neptune to Whistler
//  --------------------------------------------------------------------------

#ifndef     _APIDispatcher_
#define     _APIDispatcher_

#include "KernelResources.h"
#include "PortMessage.h"
#include "Queue.h"
#include "WorkItem.h"

//  forward decls
class   CAPIRequest; 

//  --------------------------------------------------------------------------
//  CAPIDispatchSync
//
//  Purpose [scotthan]:    
//
//      This class encapsulates the events that coordinate service shutdown.   

//      Note: We could have simply synchronized on the respective thread handles,
//      had we launched them ourselves.   Our architecture is based on
//      the worker thread pool, however, so we don't have access to thread handles.  
//      Hence, this class.
//
//      In our initial entrypoint, ServiceMain, we:
//      (1) Create the port and start polling it for requests.
//      (2) Once the polling loop exits, we wait for any pending 
//          SERVICE_CONTROL_STOP/SHUTDOWN request to complete.
//      (3) Destroy the CService object and the CAPIConnection object.
//  
//      When we get a SERVICE_CONTROL_STOP/SHUTDOWN request to our SCM entrypoint 
//      (CService::HandlerEx), we:
//      (1) Set the service status to SERVICE_STOP_PENDING. 
//      (2) Signal to all blocking LPC request handler threads that the service
//          is coming down.  This should cause them to exit gracefully and
//          come home.
//      (3) Send an API_GENERIC_STOP LPC request down the port telling it to quit. 
//          (note: this request succeeds only if it originates from within the service process.).  
//      (4) Wait for this API_GENERIC_STOP LPC request to complete, which means the 
//          LPC port is shut down and cleaned up
//      (5) Signal that the SERVICE_CONTROL_STOP/SHUTDOWN handler has finished up; it's
//          save to exit ServiceMain
//
//      In our API_GENERIC_STOP LPC request handler, we 
//      (1) Make our port deaf to new LPC requests.  
//          (note: this immediately releases the ServiceMain thread,
//          which drops out of its port polling loop and must wait for completion of the 
//          SERVICE_CONTROL_STOP/SHUTDOWN request on HandlerEx() before exiting.)
//      (2) Wait for the request queue to empty.
//      (3) Destroy the request queue and the port itself.
//      (4) Signal to the SERVICE_CONTROL_STOP/SHUTDOWN handler that we're done.
//
//      The three objects that use this class are CService, CAPIConnection, and CAPIDispatcher.
//      The CService instance owns the APIDispatcherSync class instance, and passes its address 
//      off to CAPIConnection, who in turn gives the pointer to each CAPIDispatcher it owns.
//      The object expires with its owning CService instance.
//
//  History:    2002-03-18  scotthan        created.
//  --------------------------------------------------------------------------
class CAPIDispatchSync
//  --------------------------------------------------------------------------
{
public:    
    CAPIDispatchSync();
    ~CAPIDispatchSync();

    //  Signals commencement of service stop sequence.
    static void SignalServiceStopping(CAPIDispatchSync* pds);
    //  Reports whether service is in stop sequence.
    static BOOL IsServiceStopping(CAPIDispatchSync* pds);
    //  Retrieves the service stopping event.
    static HANDLE GetServiceStoppingEvent(CAPIDispatchSync* pds);

    //  API request dispatch 'anti-semaphore', signals when no more requests
    //  are pending.   Each time a request is queued, DispatchEnter() is 
    //  called.   Each time a request is unqueued, DispatchLeave() is called
    static void  DispatchEnter(CAPIDispatchSync*);
    static void  DispatchLeave(CAPIDispatchSync*);

    //  Invoked by the CAPIConnection API_GENERIC_STOP handler to wait for 
    //  all outstanding LPC requests to come home and be dequeued.
    static DWORD WaitForZeroDispatches(CAPIDispatchSync* pds, DWORD dwTimeout);

    //  The CAPIConnection API_GENERIC_STOP handler calls this to signal 
    //  that the port has been shut down and cleaned up.
    static void  SignalPortShutdown(CAPIDispatchSync* pds);

    //  Invoked by CService::HandlerEx to await port cleanup.
    static DWORD WaitForPortShutdown(CAPIDispatchSync* pds, DWORD dwTimeout);

    //  CService::HandlerEx calls this to signal ServiceMain that the
    //  SERVICE_CONTROL_STOP/SHUTDOWN sequence has completed, and its safe to exit.
    static void  SignalServiceControlStop(CAPIDispatchSync* pds);

    //  Invoked by ServiceMain (in CService::Start) to wait for completion of
    //  the stop control process is done.   
    static DWORD WaitForServiceControlStop(CAPIDispatchSync* pds, DWORD dwTimeout);


    #define DISPATCHSYNC_TIMEOUT  60000

private:
    
    void Lock();
    void Unlock();

    CRITICAL_SECTION _cs;           // serializes signalling of events
    LONG             _cDispatches;  // count of outstanding asynchronous API request dispatches.
    

    //  Since we're architected based entirely on nt worker threads, 
    //  we have no thread handles to wait on.   Instead, we rely on the sequential 
    //  firing of the following events.   
    
    //  In chronologoical order of firing:
    HANDLE           _hServiceStopping;    // Signaled when service begins stop sequence.
    HANDLE           _hZeroDispatches;     // This is fired when API request queue is empty.  
                                           //   The API_GENERIC_STOP handler shuts down the port and 
                                           //   then waits on this before proceeding with queue destruction.
    HANDLE           _hPortShutdown;       // This is fired when the API_GENERIC_STOP handler is done 
                                           //   cleaning up the request queue.  The service's control SERVICE_CONTROL_STOP
                                           //   code path in HandlerEx waits on this before signalling
                                           //   _hServiceControlStop and returning to the SCM.
    HANDLE           _hServiceControlStop; // ServiceMain waits on this before completing shutdown by 
                                           //   destroying the CService instance and exiting.
};


//  --------------------------------------------------------------------------
//  CAPIDispatcher
//
//  Purpose:    This class processes requests from a client when signaled to.
//              CAPIDispatcher::QueueRequest is called by a thread which
//              monitors an LPC port. Once the request is queued an event is
//              signaled to wake the thread which processes client requests.
//              The thread processes all queued requests and wait for the
//              event to be signaled again.
//
//  History:    1999-11-07  vtan        created
//              2000-08-25  vtan        moved from Neptune to Whistler
//  --------------------------------------------------------------------------

class   CAPIDispatcher : public CWorkItem
{
    private:
        friend  class   CCatchCorruptor;

                                    CAPIDispatcher (void);
    public:
                                    CAPIDispatcher (HANDLE hClientProcess);
        virtual                     ~CAPIDispatcher (void);

                HANDLE              GetClientProcess (void)     const;
                DWORD               GetClientSessionID (void)   const;
                void                SetPort (HANDLE hPort);
                HANDLE              GetSection (void);
                void*               GetSectionAddress (void)    const;
                NTSTATUS            CloseConnection (void);
                NTSTATUS            QueueRequest (const CPortMessage& portMessage, CAPIDispatchSync* pAPIDispatchSync);
                NTSTATUS            ExecuteRequest (const CPortMessage& portMessage);
                NTSTATUS            RejectRequest (const CPortMessage& portMessage, NTSTATUS status)    const;
        virtual NTSTATUS            CreateAndQueueRequest (const CPortMessage& portMessage) = 0;
        virtual NTSTATUS            CreateAndExecuteRequest (const CPortMessage& portMessage) = 0;
    protected:
        virtual void                Entry (void);
                NTSTATUS            Execute (CAPIRequest *pAPIRequest)  const;
        virtual NTSTATUS            CreateSection (void);

                NTSTATUS            SignalRequestPending (void);
    private:
                NTSTATUS            SendReply (const CPortMessage& portMessage)     const;
#ifdef      DEBUG
        static  bool                ExcludedStatusCodeForDebug (NTSTATUS status);
#endif  /*  DEBUG   */
        static  LONG        WINAPI  DispatcherExceptionFilter (struct _EXCEPTION_POINTERS *pExceptionInfo);
    protected:
                HANDLE              _hSection;
                void*               _pSection;
                CQueue              _queue;
                CAPIDispatchSync*   _pAPIDispatchSync;
    private:
                HANDLE              _hProcessClient;
                HANDLE              _hPort;
                bool                _fRequestsPending,
                                    _fConnectionClosed;
                CCriticalSection    _lock;
};

#endif  /*  _APIDispatcher_     */