localep.h

Go to the documentation of this file.

/*
 * localep.h
 *
 * Local EndPoint/Connection.
 *
 * Open Phone Abstraction Library (OPAL)
 * Formally known as the Open H323 project.
 *
 * Copyright (c) 2008 Vox Lucida Pty. Ltd.
 *
 * The contents of this file are subject to the Mozilla Public License
 * Version 1.0 (the "License"); you may not use this file except in
 * compliance with the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS"
 * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 * the License for the specific language governing rights and limitations
 * under the License.
 *
 * The Original Code is Open Phone Abstraction Library.
 *
 * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
 *
 * Contributor(s): ______________________________________.
 */

#ifndef OPAL_OPAL_LOCALEP_H
#define OPAL_OPAL_LOCALEP_H

#ifdef P_USE_PRAGMA
#pragma interface
#endif

#include <opal_config.h>

#include <opal/endpoint.h>


class OpalLocalConnection;
class OpalH224Handler;
class OpalFarEndCameraControl;


#define OPAL_LOCAL_PREFIX "local"

#define OPAL_OPT_EXPLICIT_ALERTING "Explicit-Alerting"


class OpalLocalEndPoint : public OpalEndPoint
{
    PCLASSINFO(OpalLocalEndPoint, OpalEndPoint);
  public:
    OpalLocalEndPoint(
      OpalManager & manager,         
      const char * prefix = OPAL_LOCAL_PREFIX, 
      bool useCallbacks = true       
    );

    ~OpalLocalEndPoint();

    virtual OpalMediaFormatList GetMediaFormats() const;

    virtual PSafePtr<OpalConnection> MakeConnection(
      OpalCall & call,           
      const PString & party,     
      void * userData = NULL,    
      unsigned int options = 0,  
      OpalConnection::StringOptions * stringOptions  = NULL 
    );

    PSafePtr<OpalLocalConnection> GetLocalConnectionWithLock(
      const PString & token,     
      PSafetyMode mode = PSafeReadWrite   
    ) { return GetConnectionWithLockAs<OpalLocalConnection>(token, mode); }

    virtual OpalLocalConnection * CreateConnection(
      OpalCall & call,    
      void * userData,    
      unsigned options,   
      OpalConnection::StringOptions * stringOptions 
    );

    virtual bool OnOutgoingSetUp(
      const OpalLocalConnection & connection 
    );

    virtual bool OnOutgoingCall(
      const OpalLocalConnection & connection 
    );

    virtual bool OnIncomingCall(
      OpalLocalConnection & connection 
    );

    virtual bool AlertingIncomingCall(
      const PString & token, 
      OpalConnection::StringOptions * options = NULL,  
      bool withMedia = false  
    );

    virtual bool AcceptIncomingCall(
      const PString & token, 
      OpalConnection::StringOptions * options = NULL  
    );

    virtual bool RejectIncomingCall(
      const PString & token,                 
      const OpalConnection::CallEndReason & reason = OpalConnection::EndedByAnswerDenied 
    );

    virtual bool OnUserInput(
      const OpalLocalConnection & connection, 
      const PString & indication    
    );

    P_DECLARE_BITWISE_ENUM(CallbackUsage, 2, (NoCallbacks, UseSourceCallback, UseSinkCallback));

    typedef map<OpalMediaType, CallbackUsage> CallbackMap;

    bool UseCallback(
      const OpalMediaFormat & mediaFormat,  
      bool isSource                         
    ) const;

    bool SetCallbackUsage(
      const OpalMediaType & mediaType,
      CallbackUsage usage
    );

    virtual bool OnReadMediaFrame(
      const OpalLocalConnection & connection, 
      const OpalMediaStream & mediaStream,    
      RTP_DataFrame & frame                   
    );

    virtual bool OnWriteMediaFrame(
      const OpalLocalConnection & connection, 
      const OpalMediaStream & mediaStream,    
      RTP_DataFrame & frame                   
    );

    virtual bool OnReadMediaData(
      OpalLocalConnection & connection, 
      OpalMediaStream & mediaStream,    
      void * data,                      
      PINDEX size,                      
      PINDEX & length                   
    );

    virtual bool OnWriteMediaData(
      const OpalLocalConnection & connection, 
      const OpalMediaStream & mediaStream,    
      const void * data,                      
      PINDEX length,                          
      PINDEX & written                        
    );

#if OPAL_VIDEO

    virtual bool CreateVideoInputDevice(
      const OpalConnection & connection,    
      const OpalMediaFormat & mediaFormat,  
      PVideoInputDevice * & device,         
      bool & autoDelete                     
    );

    virtual bool CreateVideoOutputDevice(
      const OpalConnection & connection,    
      const OpalMediaFormat & mediaFormat,  
      bool preview,                         
      PVideoOutputDevice * & device,        
      bool & autoDelete                     
    );
#endif

    enum Synchronicity {
      e_Synchronous,        
      e_Asynchronous,       
      e_SimulateSynchronous 
    };

    virtual Synchronicity GetSynchronicity(
      const OpalMediaFormat & mediaFormat,  
      bool isSource                         
    ) const;

    Synchronicity GetDefaultAudioSynchronicity() const { return m_defaultAudioSynchronicity; }

    void SetDefaultAudioSynchronicity(Synchronicity sync) { m_defaultAudioSynchronicity = sync; }

#if OPAL_VIDEO

    Synchronicity GetDefaultVideoSourceSynchronicity() const { return m_defaultVideoSourceSynchronicity; }

    void SetDefaultVideoSourceSynchronicity(Synchronicity sync) { m_defaultVideoSourceSynchronicity = sync; }
#endif // OPAL_VIDEO

    bool IsDeferredAlerting() const { return m_deferredAlerting; }

    void SetDeferredAlerting(bool defer) { m_deferredAlerting = defer; }

    bool IsDeferredAnswer() const { return m_deferredAnswer; }

    void SetDeferredAnswer(bool defer) { m_deferredAnswer = defer; }

    bool WillPauseTransmitMediaOnHold() const { return m_pauseTransmitMediaOnHold; }

    void SetPauseTransmitMediaOnHold(bool pause) { m_pauseTransmitMediaOnHold = pause; }

#if OPAL_HAS_H281
    void SetFarEndCameraCapabilityChangedNotifier(const PNotifier & notifier) { m_farEndCameraCapabilityChangedNotifier = notifier; }

    const PNotifier & GetFarEndCameraCapabilityChangedNotifier() const { return m_farEndCameraCapabilityChangedNotifier; }

    void SetFarEndCameraActionNotifier(const PNotifier & notifier) { m_farEndCameraActionNotifier = notifier; }

    const PNotifier & GetFarEndCameraActionNotifier() const { return m_farEndCameraActionNotifier; }
#endif // OPAL_HAS_H281


  protected:
    bool m_deferredAlerting;
    bool m_deferredAnswer;
    bool m_pauseTransmitMediaOnHold;

    CallbackMap m_useCallback;

    Synchronicity m_defaultAudioSynchronicity;
#if OPAL_VIDEO
    Synchronicity m_defaultVideoSourceSynchronicity;
#endif // OPAL_VIDEO

#if OPAL_HAS_H281
    PNotifier m_farEndCameraCapabilityChangedNotifier;
    PNotifier m_farEndCameraActionNotifier;
#endif // OPAL_HAS_H281

  private:
    P_REMOVE_VIRTUAL(OpalLocalConnection *, CreateConnection(OpalCall &, void *), 0);
    P_REMOVE_VIRTUAL(bool, IsSynchronous() const, false);
};


class OpalLocalConnection : public OpalConnection
{
    PCLASSINFO(OpalLocalConnection, OpalConnection);
  public:
    OpalLocalConnection(
      OpalCall & call,              
      OpalLocalEndPoint & endpoint, 
      void * userData,              
      unsigned options,             
      OpalConnection::StringOptions * stringOptions, 
      char tokenPrefix = 'L'        
    );

    ~OpalLocalConnection();

    virtual PBoolean OnIncomingConnection(unsigned int options, OpalConnection::StringOptions * stringOptions);

    virtual PBoolean IsNetworkConnection() const { return false; }

    virtual void OnApplyStringOptions();

    virtual PBoolean SetUpConnection();

    virtual PBoolean SetAlerting(
      const PString & calleeName,   
      PBoolean withMedia            
    );

    virtual PBoolean SetConnected();

    virtual bool HoldRemote(
      bool placeOnHold  
    );

    virtual OpalMediaStream * CreateMediaStream(
      const OpalMediaFormat & mediaFormat, 
      unsigned sessionID,                  
      PBoolean isSource                    
    );

    virtual void OnClosedMediaStream(
      const OpalMediaStream & stream     
    );

    virtual PBoolean SendUserInputString(
      const PString & value                   
    );

    virtual bool OnOutgoingSetUp();

    virtual bool OnOutgoing();

    virtual bool OnIncoming();

    virtual void AlertingIncoming(
      bool withMedia = false  
    );

    virtual void AcceptIncoming();


    virtual bool OnReadMediaFrame(
      const OpalMediaStream & mediaStream,    
      RTP_DataFrame & frame                   
    );

    virtual bool OnWriteMediaFrame(
      const OpalMediaStream & mediaStream,    
      RTP_DataFrame & frame                   
    );

    virtual bool OnReadMediaData(
      OpalMediaStream & mediaStream, 
      void * data,                   
      PINDEX size,                   
      PINDEX & length                
    );

    virtual bool OnWriteMediaData(
      const OpalMediaStream & mediaStream,    
      const void * data,                      
      PINDEX length,                          
      PINDEX & written                        
    );

    virtual OpalLocalEndPoint::Synchronicity GetSynchronicity(
      const OpalMediaFormat & mediaFormat,  
      bool isSource                         
    ) const;

#if OPAL_VIDEO

    virtual bool CreateVideoInputDevice(
      const OpalMediaFormat & mediaFormat,  
      PVideoInputDevice * & device,         
      bool & autoDelete                     
    );

    virtual bool CreateVideoOutputDevice(
      const OpalMediaFormat & mediaFormat,  
      bool preview,                         
      PVideoOutputDevice * & device,        
      bool & autoDelete                     
    );

    virtual bool ChangeVideoInputDevice(
      const PVideoDevice::OpenArgs & device,  
      unsigned sessionID = 0                  
    );

    virtual bool ChangeVideoOutputDevice(
      const PVideoDevice::OpenArgs & device,  
      unsigned sessionID = 0,                 
      bool preview = false                    
    );
#endif // OPAL_VIDEO

#if OPAL_HAS_H281

    bool FarEndCameraControl(
      PVideoControlInfo::Types what,      
      int direction = 0,                  
      const PTimeInterval & duration = 0  
    );

    void SetFarEndCameraCapabilityChangedNotifier(const PNotifier & notifier);

    void SetFarEndCameraActionNotifier(const PNotifier & notifier);
#endif // OPAL_HAS_H281


    void * GetUserData() const  { return m_userData; }

    void SetUserData(void * v)  { m_userData = v; }

  protected:
    friend class PSafeWorkNoArg<OpalLocalConnection>;
    void InternalAcceptIncoming();

    OpalLocalEndPoint & m_endpoint;
    void              * m_userData;

#if OPAL_HAS_H224
    OpalH224Handler * m_h224Handler;
#endif
#if OPAL_HAS_H281
    OpalFarEndCameraControl * m_farEndCameraControl;
#endif
};


class OpalLocalMediaStream : public OpalMediaStream, public OpalMediaStreamPacing
{
    PCLASSINFO(OpalLocalMediaStream, OpalMediaStream);
  public:
    OpalLocalMediaStream(
      OpalLocalConnection & conn,          
      const OpalMediaFormat & mediaFormat, 
      unsigned sessionID,                  
      bool isSource,                       
      OpalLocalEndPoint::Synchronicity synchronicity 
    );

    virtual PBoolean ReadPacket(
      RTP_DataFrame & packet
    );

    virtual PBoolean WritePacket(
      RTP_DataFrame & packet
    );

    virtual PBoolean ReadData(
      BYTE * data,      
      PINDEX size,      
      PINDEX & length   
    );

    virtual PBoolean WriteData(
      const BYTE * data,   
      PINDEX length,       
      PINDEX & written     
    );

    virtual PBoolean IsSynchronous() const;

  protected:
    virtual void InternalClose() { }

    OpalLocalConnection            & m_connection;
    OpalLocalEndPoint::Synchronicity m_synchronicity;
    PBYTEArray                       m_silence;
    PTRACE_THROTTLE(m_readLogThrottle, 3, 60000, 5);
    PTRACE_THROTTLE(m_writeLogThrottle, 3, 60000, 5);
};


#endif // OPAL_OPAL_LOCALEP_H


// End of File ///////////////////////////////////////////////////////////////