ConversationManager.hxx

Go to the documentation of this file.

#if !defined(ConversationManager_hxx)
#define ConversationManager_hxx
 
#include "BridgeMixer.hxx"
 
#include <rutil/ConfigParse.hxx>
#include <resip/stack/Uri.hxx>
#include <resip/stack/Contents.hxx>
#include <resip/dum/InviteSessionHandler.hxx>
#include <resip/dum/DialogSetHandler.hxx>
#include <resip/dum/SubscriptionHandler.hxx>
#include <resip/dum/OutOfDialogHandler.hxx>
#include <resip/dum/RedirectHandler.hxx>
#include <resip/dum/PagerMessageHandler.hxx>
 
#include "MediaResourceCache.hxx"
#include "MediaEvent.hxx"
#include "HandleTypes.hxx"
 
#include <atomic>
#include <memory>
#include <mutex>
 
namespace resip
{
class DialogUsageManager;
}
 
namespace recon
{
class Conversation;
class RelatedConversationSet;
class Participant;
class UserAgent;
class ConversationProfile;
class LocalParticipant;
class MediaResourceParticipant;
class MediaStackAdapter;
class RemoteParticipant;
class RemoteParticipantDialogSet;
 
 
class ConversationManager : public resip::InviteSessionHandler,
   public resip::DialogSetHandler,
   public resip::OutOfDialogHandler,
   public resip::ClientSubscriptionHandler,
   public resip::ServerSubscriptionHandler,
   public resip::RedirectHandler,
   public resip::ClientPagerMessageHandler,
   public resip::ServerPagerMessageHandler
{
public:
 
   ConversationManager(std::shared_ptr<MediaStackAdapter> mediaStackAdapter,
      std::shared_ptr<resip::ConfigParse> configParse = std::shared_ptr<resip::ConfigParse>());
   virtual ~ConversationManager();
 
   typedef enum
   {
      ParticipantType_Local,
      ParticipantType_Remote,
      ParticipantType_MediaResource,
      ParticipantType_RemoteIMPager,
      ParticipantType_RemoteIMSession
   } ParticipantType;
   static const char* participantTypeToString(ParticipantType partType);
 
   typedef enum
   {
      // Create a conversation for each early fork. Accept the first fork 
      // from which a 200 is received.  Automatically kill other forks on
      // answer only.  In this mode, applications wishing to end a call 
      // before answer must destory each related participant/conversation 
      // seperately, causing a BYE to be sent to each leg that has 
      // established an early dialog, followed by a CANCEL after all 
      // related legs are destroyed
      ForkSelectAutomatic,
      // Create a conversation for each early fork. Let the application 
      // dispose of extra forks. ex: app may form conference. 
      ForkSelectManual,
      // Create a conversation for each early fork. Accept the first fork 
      // from which a 200 is received.  Automatically kill other forks on
      // answer or if the original participant is destroyed.  Also issues 
      // a single CANCEL request if original participant is destroyed before 
      // answer.
      ForkSelectAutomaticEx,
   } ParticipantForkSelectMode;
 
   typedef enum
   {
      // Never auto hold, only hold if holdParticipant API is used
      AutoHoldDisabled,
      // Default.  Automatically put a RemoteParticipant on-hold if there 
      // are no other participants in the conversation with them.
      AutoHoldEnabled,
      // Use this if you are broadcasting media to all participants and 
      // don't need to receive any inbound media.  All participants in
      // the conversation will be SIP held and will receive media from 
      // an added MediaParticipant. Remote offers with inactive will be
      // responded with sendonly as well. This option is useful for 
      // implementing music on hold servers. 
      AutoHoldBroadcastOnly
   } AutoHoldMode;
 
   typedef enum
   {
      RedirectSuccessOnTrying,    // Consider redirect to be successful on Notify SipFrag 100
      RedirectSuccessOnRinging,   // Consider redirect to be successful on Notify SipFrag 18x
      RedirectSuccessOnConnected  // Consider redirect to be successful on Notify SipFrag 2xx
   } RedirectSuccessCondition;
 
   // Conversation methods  //////////////////////////////////////////////
 
   virtual ConversationHandle createConversation(AutoHoldMode autoHoldMode = AutoHoldEnabled);
 
   virtual void destroyConversation(ConversationHandle convHandle);
 
   virtual void joinConversation(ConversationHandle sourceConvHandle, ConversationHandle destConvHandle);
 
   // Participant methods  ///////////////////////////////////////////////
 
   virtual ParticipantHandle createRemoteParticipant(ConversationHandle convHandle, 
                                                     const resip::NameAddr& destination, 
                                                     ParticipantForkSelectMode forkSelectMode = ForkSelectAutomatic,
                                                     const std::shared_ptr<ConversationProfile>& conversationProfile = nullptr,
                                                     const std::multimap<resip::Data, resip::Data>& extraHeaders = std::multimap<resip::Data, resip::Data>());
 
   virtual ParticipantHandle createRemoteIMPagerParticipant(const resip::NameAddr& destination,
                                                            const std::shared_ptr<ConversationProfile>& conversationProfile = nullptr);
 
   virtual ParticipantHandle createRemoteIMSessionParticipant(const resip::NameAddr& destination,
      ParticipantForkSelectMode forkSelectMode = ForkSelectAutomatic,
      const std::shared_ptr<ConversationProfile>& callerProfile = nullptr,
      const std::multimap<resip::Data, resip::Data>& extraHeaders = std::multimap<resip::Data, resip::Data>());
 
   virtual ParticipantHandle createMediaResourceParticipant(ConversationHandle convHandle, const resip::Uri& mediaUrl, const std::shared_ptr<resip::Data>& playAudioBuffer = std::shared_ptr<resip::Data>(), void* recordingCircularBuffer = 0);
 
   virtual ParticipantHandle createLocalParticipant();
 
   virtual void destroyParticipant(ParticipantHandle partHandle);
 
   virtual void addParticipant(ConversationHandle convHandle, ParticipantHandle partHandle);
 
   virtual void removeParticipant(ConversationHandle convHandle, ParticipantHandle partHandle);
 
   virtual void moveParticipant(ParticipantHandle partHandle, ConversationHandle sourceConvHandle, ConversationHandle destConvHandle);
 
   virtual void modifyParticipantContribution(ConversationHandle convHandle, ParticipantHandle partHandle, unsigned int inputGain, unsigned int outputGain);
 
   virtual void modifyParticipantRecordChannel(ParticipantHandle partHandle, unsigned int channelNum);
 
   virtual void outputBridgeMatrix(ConversationHandle convHandle = 0);
 
   virtual void alertParticipant(ParticipantHandle partHandle, bool earlyFlag = true);
 
   virtual void answerParticipant(ParticipantHandle partHandle);
 
   virtual void rejectParticipant(ParticipantHandle partHandle, unsigned int rejectCode);
 
   virtual void redirectParticipant(ParticipantHandle partHandle, const resip::NameAddr& destination, unsigned int redirectCode = 302, RedirectSuccessCondition successCondition = RedirectSuccessOnConnected);
 
   virtual void redirectToParticipant(ParticipantHandle partHandle, ParticipantHandle destPartHandle, RedirectSuccessCondition successCondition = RedirectSuccessOnConnected);
 
   virtual void holdParticipant(ParticipantHandle partHandle, bool hold);
 
   virtual void sendIMToParticipant(ParticipantHandle partHandle, std::unique_ptr<resip::Contents> contents);
 
   virtual void addBufferToMediaResourceCache(const resip::Data& name, const resip::Data& buffer, int type);
 
   virtual bool getBufferFromMediaResourceCache(const resip::Data& name, resip::Data** buffer, int* type);
   
   virtual void requestKeyframe(ParticipantHandle partHandle, std::chrono::duration<double> durationMs);
   virtual void requestKeyframeFromPeer(ParticipantHandle partHandle, std::chrono::duration<double> durationMs);
   virtual void requestKeyframeFromPeerRecurring(ParticipantHandle partHandle, std::chrono::duration<double> interval);
   virtual void startApplicationTimer(unsigned int timerId, unsigned int timerData1, unsigned int timerData2, unsigned int durationMs);
 
   virtual void startApplicationTimer(unsigned int timerId, unsigned int timerData1, unsigned int timerData2, std::chrono::duration<double> duration);
 
   // Override this to handle the callback
   virtual void onApplicationTimer(unsigned int timerId, unsigned int timerData1, unsigned int timerData2) { }
 
 
   // Conversation Manager Handlers //////////////////////////////////////
 
   // !slg! Note: We should eventually be passing back a generic ParticipantInfo object
   //             and not the entire SipMessage for these callbacks
 
   virtual void onIncomingParticipant(ParticipantHandle partHandle, const resip::SipMessage& msg, bool autoAnswer, ConversationProfile& conversationProfile) = 0;
 
   virtual void onIncomingIMPagerParticipant(ParticipantHandle partHandle, const resip::SipMessage& msg, ConversationProfile& conversationProfile) { rejectParticipant(partHandle, 501); }
 
   virtual void onIncomingIMSessionParticipant(ParticipantHandle partHandle, const resip::SipMessage& msg, bool autoAnswer, ConversationProfile& conversationProfile) { rejectParticipant(partHandle, 501); }
 
   virtual bool onReceiveIMFromParticipant(ParticipantHandle partHandle, const resip::SipMessage& msg) { return false; }
 
   virtual void onParticipantSendIMFailure(ParticipantHandle partHandle, const resip::SipMessage& status, std::unique_ptr<resip::Contents> contents) {}
 
   virtual void onRequestOutgoingParticipant(ParticipantHandle partHandle, const resip::SipMessage& msg, ConversationProfile& conversationProfile) = 0;
 
   virtual void onParticipantTerminated(ParticipantHandle partHandle, unsigned int statusCode) = 0;
 
   virtual void onParticipantTerminated(ParticipantHandle partHandle, unsigned int statusCode, const resip::Data& reason) { onParticipantTerminated(partHandle, statusCode); }
 
   virtual void onConversationDestroyed(ConversationHandle convHandle) = 0;
 
   virtual void onParticipantDestroyed(ParticipantHandle partHandle) = 0;
 
   virtual void onParticipantDestroyed(ParticipantHandle partHandle, ParticipantType partType) { onParticipantDestroyed(partHandle); }
 
   virtual void onRelatedConversation(ConversationHandle relatedConvHandle, ParticipantHandle relatedPartHandle, 
                                      ConversationHandle origConvHandle, ParticipantHandle origPartHandle) = 0;
 
   
   virtual void onParticipantProceeding(ParticipantHandle partHandle, const resip::SipMessage& msg) { }
 
   virtual void onParticipantAlerting(ParticipantHandle partHandle, const resip::SipMessage& msg) = 0;
 
   virtual void onParticipantConnected(ParticipantHandle partHandle, const resip::SipMessage& msg) = 0;
 
   virtual void onParticipantConnectedConfirmed(ParticipantHandle partHandle, const resip::SipMessage& msg) {}
 
   virtual void onParticipantRedirectSuccess(ParticipantHandle partHandle) = 0;
 
   virtual void onParticipantRedirectFailure(ParticipantHandle partHandle, unsigned int statusCode) = 0;
 
   virtual void onDtmfEvent(ParticipantHandle partHandle, int dtmf, int duration, bool up) = 0;
 
   virtual void onParticipantRequestedHold(ParticipantHandle partHandle, bool held) = 0;
 
   virtual void onParticipantVoiceActivity(recon::ParticipantHandle partHandle, bool on, bool inbound) {}
 
   virtual void onMediaResourceParticipantFailed(ParticipantHandle partHandle) {}
 
   virtual RemoteParticipant* createAppropriateRemoteParticipantInstance(resip::DialogUsageManager& dum, RemoteParticipantDialogSet& rpds);
   virtual RemoteParticipant* createAppropriateRemoteParticipantInstance(ParticipantHandle partHandle, resip::DialogUsageManager& dum, RemoteParticipantDialogSet& rpds);
   virtual RemoteParticipantDialogSet* createRemoteIMSessionParticipantDialogSetInstance(
      ConversationManager::ParticipantForkSelectMode forkSelectMode = ConversationManager::ForkSelectAutomatic,
      std::shared_ptr<ConversationProfile> conversationProfile = nullptr);
 
   virtual void setMediaStackAdapter(std::shared_ptr<MediaStackAdapter> mediaStackAdapter);
   MediaStackAdapter& getMediaStackAdapter() { return *mMediaStackAdapter; };
 
   std::shared_ptr<resip::ConfigParse> getConfig() { return mConfigParse; };
 
   bool sendKeyframesAtStart() const { return !mKeyframeIntervals.empty(); };
 
protected:
 
   // Invite Session Handler /////////////////////////////////////////////////////
   using InviteSessionHandler::onReadyToSend;
   virtual void onNewSession(resip::ClientInviteSessionHandle h, resip::InviteSession::OfferAnswerType oat, const resip::SipMessage& msg);
   virtual void onNewSession(resip::ServerInviteSessionHandle h, resip::InviteSession::OfferAnswerType oat, const resip::SipMessage& msg);
   virtual void onFailure(resip::ClientInviteSessionHandle h, const resip::SipMessage& msg);
   virtual void onEarlyMedia(resip::ClientInviteSessionHandle, const resip::SipMessage&, const resip::SdpContents&);
   virtual void onProvisional(resip::ClientInviteSessionHandle, const resip::SipMessage& msg);
   virtual void onConnected(resip::ClientInviteSessionHandle h, const resip::SipMessage& msg);
   virtual void onConnected(resip::InviteSessionHandle, const resip::SipMessage& msg);
   virtual void onConnectedConfirmed(resip::InviteSessionHandle, const resip::SipMessage &msg);
   virtual void onStaleCallTimeout(resip::ClientInviteSessionHandle);
   virtual void onTerminated(resip::InviteSessionHandle h, resip::InviteSessionHandler::TerminatedReason reason, const resip::SipMessage* msg);
   virtual void onRedirected(resip::ClientInviteSessionHandle, const resip::SipMessage& msg);
   virtual void onAnswer(resip::InviteSessionHandle, const resip::SipMessage& msg, const resip::SdpContents&);
   virtual void onOffer(resip::InviteSessionHandle handle, const resip::SipMessage& msg, const resip::SdpContents& offer);
   virtual void onOfferRequired(resip::InviteSessionHandle, const resip::SipMessage& msg);
   virtual void onOfferRejected(resip::InviteSessionHandle, const resip::SipMessage* msg);
   virtual void onOfferRequestRejected(resip::InviteSessionHandle, const resip::SipMessage& msg);
   virtual void onRemoteSdpChanged(resip::InviteSessionHandle, const resip::SipMessage& msg, const resip::SdpContents& sdp);
   virtual void onInfo(resip::InviteSessionHandle, const resip::SipMessage& msg);
   virtual void onInfoSuccess(resip::InviteSessionHandle, const resip::SipMessage& msg);
   virtual void onInfoFailure(resip::InviteSessionHandle, const resip::SipMessage& msg);
   virtual void onRefer(resip::InviteSessionHandle, resip::ServerSubscriptionHandle, const resip::SipMessage& msg);
   virtual void onReferAccepted(resip::InviteSessionHandle, resip::ClientSubscriptionHandle, const resip::SipMessage& msg);
   virtual void onReferRejected(resip::InviteSessionHandle, const resip::SipMessage& msg);
   virtual void onReferNoSub(resip::InviteSessionHandle, const resip::SipMessage& msg);
   virtual void onMessage(resip::InviteSessionHandle, const resip::SipMessage& msg);
   virtual void onMessageSuccess(resip::InviteSessionHandle, const resip::SipMessage& msg);
   virtual void onMessageFailure(resip::InviteSessionHandle, const resip::SipMessage& msg);
   virtual void onForkDestroyed(resip::ClientInviteSessionHandle);
 
   // DialogSetHandler  //////////////////////////////////////////////
   virtual void onTrying(resip::AppDialogSetHandle, const resip::SipMessage& msg);
   virtual void onNonDialogCreatingProvisional(resip::AppDialogSetHandle, const resip::SipMessage& msg);
 
   // ClientSubscriptionHandler ///////////////////////////////////////////////////
   using ClientSubscriptionHandler::onReadyToSend;
   virtual void onUpdatePending(resip::ClientSubscriptionHandle h, const resip::SipMessage& notify, bool outOfOrder);
   virtual void onUpdateActive(resip::ClientSubscriptionHandle h, const resip::SipMessage& notify, bool outOfOrder);
   virtual void onUpdateExtension(resip::ClientSubscriptionHandle, const resip::SipMessage& notify, bool outOfOrder);
   virtual void onTerminated(resip::ClientSubscriptionHandle h, const resip::SipMessage* notify);
   virtual void onNewSubscription(resip::ClientSubscriptionHandle h, const resip::SipMessage& notify);
   virtual int  onRequestRetry(resip::ClientSubscriptionHandle h, int retryMinimum, const resip::SipMessage& notify);
 
   // ServerSubscriptionHandler ///////////////////////////////////////////////////
   virtual void onNewSubscription(resip::ServerSubscriptionHandle, const resip::SipMessage& sub);
   virtual void onNewSubscriptionFromRefer(resip::ServerSubscriptionHandle, const resip::SipMessage& sub);
   virtual void onRefresh(resip::ServerSubscriptionHandle, const resip::SipMessage& sub);
   virtual void onTerminated(resip::ServerSubscriptionHandle);
   virtual void onReadyToSend(resip::ServerSubscriptionHandle, resip::SipMessage&);
   virtual void onNotifyRejected(resip::ServerSubscriptionHandle, const resip::SipMessage& msg);      
   virtual void onError(resip::ServerSubscriptionHandle, const resip::SipMessage& msg);      
   virtual void onExpiredByClient(resip::ServerSubscriptionHandle, const resip::SipMessage& sub, resip::SipMessage& notify);
   virtual void onExpired(resip::ServerSubscriptionHandle, resip::SipMessage& notify);
   virtual bool hasDefaultExpires() const;
   virtual uint32_t getDefaultExpires() const;
 
   // OutOfDialogHandler //////////////////////////////////////////////////////////
   virtual void onSuccess(resip::ClientOutOfDialogReqHandle, const resip::SipMessage& response);
   virtual void onFailure(resip::ClientOutOfDialogReqHandle, const resip::SipMessage& response);
   virtual void onReceivedRequest(resip::ServerOutOfDialogReqHandle, const resip::SipMessage& request);
 
   // RedirectHandler /////////////////////////////////////////////////////////////
   virtual void onRedirectReceived(resip::AppDialogSetHandle, const resip::SipMessage& response);
   virtual bool onTryingNextTarget(resip::AppDialogSetHandle, const resip::SipMessage& request);
 
   // ClientPagerMessageHandler ///////////////////////////////////////////////////
   virtual void onSuccess(resip::ClientPagerMessageHandle, const resip::SipMessage& status);
   virtual void onFailure(resip::ClientPagerMessageHandle, const resip::SipMessage& status, std::unique_ptr<resip::Contents> contents);
 
   // ServerPagerMessageHandler ///////////////////////////////////////////////////
   virtual void onMessageArrived(resip::ServerPagerMessageHandle, const resip::SipMessage& message);
 
 
   UserAgent* getUserAgent() { return mUserAgent; }
 
   ParticipantHandle getNewParticipantHandle();    // thread safe
 
   void post(resip::Message *message);
   void post(resip::ApplicationMessage& message, std::chrono::duration<double> duration=std::chrono::milliseconds::zero());
 
   virtual void setUserAgent(UserAgent *userAgent);
 
   friend class MediaStackAdapter;
   std::shared_ptr<BridgeMixer>& getBridgeMixer() { return mBridgeMixer; }
 
   ConversationHandle getNewConversationHandle();  // thread safe
   Conversation* getConversation(ConversationHandle convHandle);
 
   std::set<ConversationHandle> getConversationHandles() const;  // thread safe
   std::set<ParticipantHandle> getParticipantHandlesByType(ParticipantType participantType) const;  // thread safe
 
   bool isShuttingDown() { return mShuttingDown; }
 
   bool remoteParticipantInitialHold() { return mConfigParse ? mConfigParse->getConfigBool("RemoteParticipantInitialHold", true) : true; }
   const std::vector<int>& keyframeIntervals() const { return mKeyframeIntervals; }
 
private:
   friend class DefaultDialogSet;
   friend class Subscription;
 
   friend class UserAgentShutdownCmd;
   void shutdown(void);
 
   // Note:  In general the following fns are not thread safe and must be called from dum process 
   //        loop only
   friend class Conversation;
   friend class SipXConversation;
   friend class OutputBridgeMixWeightsCmd;
   void registerConversation(Conversation *);
   void unregisterConversation(Conversation *);
 
   friend class Participant;
   void registerParticipant(Participant *);
   void unregisterParticipant(Participant *);
 
   friend class RemoteParticipant;
   friend class RemoteIMPagerParticipant;
   friend class SipXRemoteParticipant;
   friend class RemoteIMSessionParticipant;
   friend class UserAgent;
 
   /* Called periodically in the event loop to give the ConversationManager
      the opportunity to do any pending work */
   virtual void process();
 
   friend class DtmfEvent;
   friend class MediaEvent;
   void notifyMediaEvent(ParticipantHandle partHandle, MediaEvent::MediaEventType eventType, MediaEvent::MediaDirection direction);
 
   void notifyDtmfEvent(ParticipantHandle partHandle, int dtmf, int duration, bool up);
 
   friend class RemoteParticipantDialogSet;
   friend class SipXRemoteParticipantDialogSet;
   friend class MediaResourceParticipant;
   friend class SipXMediaResourceParticipant;
   friend class LocalParticipant;
   friend class BridgeMixer;
   friend class SipXMediaInterface;
 
   // exists here (as opposed to RemoteParticipant) - since it is required for OPTIONS responses
   virtual void buildSdpOffer(ConversationProfile* profile, resip::SdpContents& offer);
 
   friend class OutputBridgeMixWeightsCmd;
 
   friend class MediaResourceParticipantDeleterCmd;
   friend class CreateConversationCmd;
   friend class DestroyConversationCmd;
   friend class JoinConversationCmd;
   friend class CreateRemoteParticipantCmd;
   friend class CreateMediaResourceParticipantCmd;
   friend class CreateLocalParticipantCmd;
   friend class DestroyParticipantCmd;
   friend class AddParticipantCmd;
   friend class RemoveParticipantCmd;
   friend class MoveParticipantCmd;
   friend class ModifyParticipantContributionCmd;
   friend class ModifyParticipantRecordChannelCmd;
   friend class AlertParticipantCmd;
   friend class AnswerParticipantCmd;
   friend class RejectParticipantCmd;
   friend class RedirectParticipantCmd;
   friend class RedirectToParticipantCmd;
   friend class HoldParticipantCmd;
   friend class CreateRemoteIMPagerParticipantCmd;
   friend class SendIMToParticipantCmd;
   friend class RequestKeyframeCmd;
   friend class RequestKeyframeFromPeerCmd;
   friend class RequestKeyframeFromPeerRecurringCmd;
 
   friend class MediaStreamReadyEvent;
   friend class MediaStreamErrorEvent;
 
   UserAgent* mUserAgent;
   std::shared_ptr<MediaStackAdapter> mMediaStackAdapter;
   std::shared_ptr<resip::ConfigParse> mConfigParse;
   bool mShuttingDown;
 
   typedef std::map<ConversationHandle, Conversation *> ConversationMap;
   ConversationMap mConversations;
   mutable std::mutex mConversationHandlesMutex;
   std::atomic<ConversationHandle> mCurrentConversationHandle;
   std::set<ConversationHandle> mConversationHandles;
 
   typedef std::map<ParticipantHandle, Participant *> ParticipantMap;
   ParticipantMap mParticipants;
   mutable std::mutex mParticipantHandlesMutex;
   std::atomic<ParticipantHandle> mCurrentParticipantHandle;
   Participant* getParticipant(ParticipantHandle partHandle);
   std::map<ParticipantType, std::set<ParticipantHandle>> mParticipantHandlesByType;
 
   MediaResourceCache mMediaResourceCache;
 
   std::shared_ptr<BridgeMixer> mBridgeMixer;
 
   std::vector<int> mKeyframeIntervals = { 2, 2, 5, 5, 7, 10, 20, 30 };
};
 
}
 
#endif
 
 
/* ====================================================================
 
 Copyright (c) 2021-2026, SIP Spectrum, Inc. http://www.sipspectrum.com
 Copyright (c) 2021, Daniel Pocock https://danielpocock.com
 Copyright (c) 2007-2008, Plantronics, 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. Neither the name of Plantronics nor the names of its contributors 
    may be used to endorse or promote products derived from this 
    software without specific prior written permission. 
 
 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 
 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 
 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, 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.
 
 ==================================================================== */