service.hxx

SIP（Session Initiation Protocol）是由IETF定义

#if !defined(VOCAL_SERVICE_HXX)
#define VOCAL_SERVICE_HXX

/* ====================================================================
 * The Vovida Software License, Version 1.0 
 * 
 * Copyright (c) 2000 Vovida Networks, Inc.  All rights reserved.
 * 
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in
 *    the documentation and/or other materials provided with the
 *    distribution.
 * 
 * 3. The names "VOCAL", "Vovida Open Communication Application Library",
 *    and "Vovida Open Communication Application Library (VOCAL)" must
 *    not be used to endorse or promote products derived from this
 *    software without prior written permission. For written
 *    permission, please contact [e-mail].
 *
 * 4. Products derived from this software may not be called "VOCAL", nor
 *    may "VOCAL" appear in their name, without prior written
 *    permission of Vovida Networks, Inc.
 * 
 * THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESSED OR IMPLIED
 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND
 * NON-INFRINGEMENT ARE DISCLAIMED.  IN NO EVENT SHALL VOVIDA
 * NETWORKS, INC. OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT DAMAGES
 * IN EXCESS OF $1,000, NOR FOR ANY INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
 * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
 * USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
 * DAMAGE.
 * 
 * ====================================================================
 * 
 * This software consists of voluntary contributions made by Vovida
 * Networks, Inc. and many individuals on behalf of Vovida Networks,
 * Inc.  For more information on Vovida Networks, Inc., please see
 * <http://www.vovida.org/>.
 *
 */


static const char* const Service_hxx_Version = 
    "$Id: Service.hxx,v 1.7 2001/10/26 21:47:52 icahoon Exp $";


#include "Runnable.hxx"
#include "Writer.hxx"
#include "NonCopyable.hxx"
#include "FifoBase.h"
#include "EventObserver.hxx"
#include "EventSubject.hxx"
#include "Event.hxx"
#include "Sptr.hxx"
#include "ControlEvent.hxx"
#include "VocalCommon.hxx"
#include <string>

class VException;

namespace Vocal {
    namespace Signals {
        class SignalAction;
    }
}
    


/** Infrastructure common to VOCAL.
 */
namespace Vocal 
{


/** Infrastructure common to VOCAL to provide events based services.<br><br>
 */
namespace Services
{


using namespace Vocal::Behavioral;
using Vocal::Signals::SignalAction;


/** A Service is a Runnable that can be started, stopped, and shutdown.<br><br>
 *
 *  It has a Fifo where it blocks, and is an EventSubject, so that
 *  it can distribute Events as they arrive. Usually a Service is
 *  started in it's own Thread.
 *
 *  @see    Vocal::Runnable
 *  @see    Vocal::Behavioral::EventObserver
 *  @see    Vocal::Behavioral::EventSubject
 *  @see    Vocal::Services::Event
 *  @see    Vocal::ReturnCode
 *  @see    Vocal::Services::ControlEvent
 *  @see    Vocal::Threads::Thread
 *  @see    FifoBase
 *  @see    Sptr
 */
class Service : public Vocal::Runnable, public Vocal::IO::Writer, 
                public Vocal::NonCopyable
{

    protected:

    	/** Create a Service given an optional name.
    	 */    
    	Service(
	    const char              *   name = 0
	);


    public:
    

    	/** Virtual destructor
    	 */    
	virtual ~Service();


    	/** Accessor for Service Manager's Fifo.
	 */
	FifoBase< Sptr<Event> >     	&   getServiceManagerFifo();


    	/** Accessor for Service Manager's Fifo.
	 */
	const FifoBase< Sptr<Event> >	&   getServiceManagerFifo() const;


	/** Set the service manager fifo.
	 */
	void	setServiceManagerFifo(FifoBase< Sptr<Event> > *);


    	/** Accessors for Fifo.
	 */
	virtual	FifoBase< Sptr<Event> >     	&   getFifo() = 0;


    	/** Accessors for Fifo.
	 */
	virtual	const FifoBase< Sptr<Event> >	&   getFifo() const = 0;


    	/** Accessor for EventSubject.
	 */
	EventSubject< Sptr<Event> > 	    &	getEventSubject();


    	/** Accessor for EventSubject.
	 */
	const EventSubject< Sptr<Event> >   &	getEventSubject() const;


        /** Set the signal action. 
         */
        void                    setSignalAction(SignalAction * signalAction);
        
        
    	/** Runnable entry point.
	 */
    	virtual ReturnCode  	run();


    	/** Subscribe the message observer for incoming events.
	 */	
	void	    	    	subscribe(EventObserver< Sptr<Event> > &);


    	/** Unsubscribe the message observer for incoming events.
	 */	
	void	    	    	unsubscribe(EventObserver< Sptr<Event> > &);


	/** For logging.
	 */
	ostream &           	writeTo(ostream &) const;


        /** Returns the name of the service.
         */
        const string &          name() const;

    protected:
    

	/** User callback called when a valid start request has been issued. 
         *  A start request may be issued at the start of the service's
         *  lifetime, or after a successful stop request.
	 */
	virtual	ReturnCode      onStart();


	/** User callback called when a valid stop request has been issued. 
         *  The service manager may issue a start after a successful stop.
	 */
	virtual	ReturnCode      onStop();


	/** User callback called when a valid shutdown command has been 
         *  issued. When issued the service will be going away immediately,
         *  so you need to cleanup. The shutdown command does not require 
         *  a stop request to be made first.
	 */
	virtual	ReturnCode	onShutdown();
		

    	/** Handle an exception thrown by the fifo. The default behavior is 
    	 *  to ignore the exception. 
	 */
	virtual	void	    	onVException(VException &);


    	/** Handle an unknown exception thrown by the fifo. The default 
    	 *  behavior is to do a hardShutdown.
	 */
	virtual	void	    	onException();

        
        /** Handle the signal. Given that a signal action exists, a signal 
         *  has been caught. The default behavior is to do a hardShutdown.
         */
        virtual void            onSignalCaught();
        

    	/** Gets the message, detects if it is a control event. If
    	 *  so, it calls the appropriate callback. Otherwise the
    	 *  event is send to the subscribed observers.
	 */
    	virtual bool		processMessages(int, ReturnCode &);



    	/** A hard shutdown stops the service by calling onStop with 
    	 *  a zero stopEvent, and sends a STOP ControlEvent to the 
    	 *  service manager's fifo. It then shuts down the service by 
    	 *  calling onShutdown with a zero shutdownEvent and sends 
    	 *  the SHUTDOWN ControlEvent to the service manager's fifo.
	 */
    	void	    	    	hardShutdown(ReturnCode errorCode);


    private:


	/** Handle a start request. If the start request comes from
         *  the service manager, the start request is processed, setting 
	 *  the return code to SUCCESS. This calls the onStart callback.
	 */
	void	                start(Sptr<ControlEvent> startEvent);


	/** Handle a stop request. The default action is to return the 
	 *  stop request, setting the return code to SUCCESS. This calls
	 *  the onStop callback.
	 */
	virtual	void	    	stop(Sptr<ControlEvent> stopEvent);


	/** Handle a shutdown command. The shutdownEvent may be
    	 *  zero, indicating that the service is shutting down itself,
    	 *  usually on error. The default action is to do nothing.
	 */
	virtual	ReturnCode	shutdown(Sptr<ControlEvent> shutdownEvent);
		

	void	    	        blockSignals();
	void	    	        unblockSignals();
	bool  	                signalCaught();
	
    	int  	    	        block();


	FifoBase< Sptr<Event> >     *	myServiceManagerFifo;
    	EventSubject< Sptr<Event> > 	mySubject;
	string	    	    	    	myName;
        SignalAction                *   mySignalAction;
};


} // namespace Services
} // namespace Vocal


#endif // !defined(VOCAL_SERVICE_HXX)