skinnyep.h

Go to the documentation of this file.

/*
 * skinnyep.h
 *
 * Cisco SCCP (Skinny Client Control Protocol) support.
 *
 * Open Phone Abstraction Library (OPAL)
 * Formally known as the Open H323 project.
 *
 * Copyright (c) 2014 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 Vox Lucida Pty. Ltd.
 *
 * Contributor(s): Robert Jongbloed (robertj@voxlucida.com.au).
 */

#ifndef OPAL_SKINNY_H
#define OPAL_SKINNY_H

#include <opal_config.h>

#if OPAL_SKINNY

#include <rtp/rtpep.h>
#include <rtp/rtpconn.h>


class OpalSkinnyConnection;


class OpalSkinnyEndPoint : public OpalRTPEndPoint
{
    PCLASSINFO(OpalSkinnyEndPoint, OpalRTPEndPoint);
  public:
    OpalSkinnyEndPoint(
      OpalManager & manager,
      const char *prefix = "sccp"
      );

    virtual ~OpalSkinnyEndPoint();

    virtual void ShutDown();

    virtual PString GetDefaultTransport() const;

    virtual WORD GetDefaultSignalPort() const;

    virtual OpalMediaFormatList GetMediaFormats() const;

    virtual void NewIncomingConnection(
      OpalListener & listener,            
      const OpalTransportPtr & transport  
      );

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

    virtual PBoolean GarbageCollection();


    class PhoneDevice;

    virtual OpalSkinnyConnection * CreateConnection(
      OpalCall & call,            
      PhoneDevice & client,            
      unsigned callIdentifier,    
      const PString & dialNumber, 
      void * userData,            
      unsigned int options,
      OpalConnection::StringOptions * stringOptions = NULL
      );

    enum { DefaultDeviceType = 30016 }; // Cisco IP Communicator

    bool Register(
      const PString & server,      
      const PString & name,        
      unsigned deviceType = DefaultDeviceType,  
      const PString & localInterface = PString::Empty()  
    );

    bool Unregister(
      const PString & name         
    );

    PhoneDevice * CreatePhoneDevice(
      const PString & name,             
      unsigned deviceType,              
      const PIPAddressAndPort & binding 
    );

    PhoneDevice * GetPhoneDevice(
      const PString & name         
    ) const { return m_phoneDevices.GetAt(name); }

    PArray<PString> GetPhoneDeviceNames() const { return m_phoneDevices.GetKeys(); }


    class SkinnyMsg;

    class PhoneDevice : public PObject
    {
      PCLASSINFO(PhoneDevice, PObject);
      public:
        PhoneDevice(OpalSkinnyEndPoint & ep, const PString & name, unsigned deviceType, const PIPAddressAndPort & binding);
        ~PhoneDevice() { Close(); }

        virtual void PrintOn(ostream & strm) const;

        bool Start(const PString & server);
        bool Stop();
        void Close();

        bool SendSkinnyMsg(const SkinnyMsg & msg);

        const PString & GetName() const { return m_name; }
        unsigned GetDeviceType() const { return m_deviceType; }
        const PString & GetStatus() const { return m_status; }
        OpalTransportAddress GetRemoteAddress() const { return m_transport.GetRemoteAddress(); }

      protected:
        void HandleTransport();
        bool SendRegisterMsg();
        PDECLARE_NOTIFIER(PTimer, OpalSkinnyEndPoint::PhoneDevice, OnKeepAlive);

        template <class MSG> bool OnReceiveMsg(const MSG & msg)
        {
          PTRACE(3, "Skinny", "Received " << msg);
          return m_endpoint.OnReceiveMsg(*this, msg);
        }

        OpalSkinnyEndPoint & m_endpoint;
        PString              m_name;
        unsigned             m_deviceType;
        OpalTransportTCP     m_transport;
        PTimeInterval        m_delay;
        PString              m_status;
        PSyncPoint           m_exit;
        PTimer               m_keepAliveTimer;

        // Currently only support one call at a time
        PSafePtr<OpalSkinnyConnection> m_activeConnection;

      friend class OpalSkinnyEndPoint;
      friend class OpalSkinnyConnection;
    };


#pragma pack(1)
    class SkinnyMsg : public PObject
    {
        PCLASSINFO(SkinnyMsg, PObject);
      protected:
        SkinnyMsg(uint32_t id, PINDEX len, PINDEX extraSpace);
        void Construct(const PBYTEArray & pdu);

      public:
        uint32_t GetID() const { return m_messageId; }

        const BYTE * GetPacketPtr() const { return (const BYTE *)&m_length; }
        PINDEX       GetPacketLen() const { return m_length + sizeof(m_length) + sizeof(m_headerVersion); }

      protected:
        PINDEX   m_extraSpace;

        // Data after here is mapped to "over the wire" PDU, no polymorhic classes
        PUInt32l m_length;
        PUInt32l m_headerVersion;
        PUInt32l m_messageId;
    };

    // Note: all derived classes MUST NOT have composite members, e.g. PString
#define OPAL_SKINNY_MSG2(cls, base, id, extraSpace, vars) \
    class cls : public base \
    { \
        PCLASSINFO(cls, base); \
      public: \
        enum { ID = id }; \
        cls() : base(ID, sizeof(*this), extraSpace) { } \
        cls(const PBYTEArray & pdu) : base(ID, sizeof(*this), extraSpace) { Construct(pdu); } \
        vars \
    }; \
    virtual bool OnReceiveMsg(PhoneDevice & client, const cls & msg)

#define OPAL_SKINNY_MSG(cls, id, vars) OPAL_SKINNY_MSG2(cls, SkinnyMsg, id, 0, vars)

    OPAL_SKINNY_MSG(KeepAliveMsg, 0x0000,
      PUInt32l m_unknown;
    );

    OPAL_SKINNY_MSG(KeepAliveAckMsg, 0x0100,
    );

    struct Proto {
      uint8_t  m_version;
      uint8_t  m_flags;
      BYTE     m_unknown1;
      uint8_t  m_features; // 0x01=Dynamic Messages, 0x80=Abbreviated dialing

      friend ostream & operator<<(ostream & strm, const Proto & protocol);
    };

    OPAL_SKINNY_MSG(RegisterMsg, 0x0001,
      enum { MaxNameSize = 15 };
      char     m_deviceName[MaxNameSize+1];
      PUInt32l m_userId;
      PUInt32l m_instance;
      in_addr  m_ip;
      PUInt32l m_deviceType;
      PUInt32l m_maxStreams;
      PUInt32l m_activeStreams;
      Proto    m_protocol;
      PUInt32l m_socketType;    // 0=ASCII, 1=HEX
      BYTE     m_unknown2[4];
      char     m_macAddress[12];

      virtual void PrintOn(ostream & strm) const;
    );

    OPAL_SKINNY_MSG(RegisterAckMsg, 0x0081,
      PUInt32l m_keepAlive;
      char     m_dateFormat[6];
      BYTE     m_unknown1[2];
      PUInt32l m_secondaryKeepAlive;
      Proto    m_protocol;

      virtual void PrintOn(ostream & strm) const;
    );

    OPAL_SKINNY_MSG(RegisterRejectMsg, 0x009d,
      char m_errorText[32];
    );

    OPAL_SKINNY_MSG(UnregisterMsg, 0x0027,
    );

    OPAL_SKINNY_MSG(UnregisterAckMsg, 0x0118,
      PUInt32l m_status;
    );

    OPAL_SKINNY_MSG(PortMsg, 0x0002,
      PUInt16l m_port;

    virtual void PrintOn(ostream & strm) const;
    );

    OPAL_SKINNY_MSG(CapabilityRequestMsg, 0x009B,
    );

    OPAL_SKINNY_MSG(CapabilityResponseMsg, 0x0010,
      PUInt32l m_count;
      struct Info
      {
        PUInt32l m_codec;
        PUInt32l m_maxFramesPerPacket;
        PUInt32l m_g7231BitRate; // 1=5.3 Kbps, 2=6.4 Kbps
        char     m_unknown[4];
      } m_capability[32];

      virtual void PrintOn(ostream & strm) const;
      void SetCount(PINDEX count);
    );

    P_DECLARE_STREAMABLE_ENUM(CallStates,
      eUnknownState,
      eStateOffHook,
      eStateOnHook,
      eStateRingOut,
      eStateRingIn,
      eStateConnected,
      eStateBusy,
      eStateCongestion,
      eStateHold,
      eStateCallWaiting,
      eStateCallTransfer,
      eStateCallPark,
      eStateProceed,
      eStateCallRemoteMultiline,
      eStateInvalidNumber
    );
    OPAL_SKINNY_MSG(CallStateMsg, 0x0111,
      PUInt32l m_state;
      PUInt32l m_lineInstance;
      PUInt32l m_callIdentifier;
      BYTE     m_unknown[12];

      __inline CallStates GetState() const { return (CallStates)(uint32_t)m_state; }
      virtual void PrintOn(ostream & strm) const;
    );

    P_DECLARE_STREAMABLE_ENUM(CallType,
      eTypeUnknownCall,
      eTypeInboundCall,
      eTypeOutboundCall,
      eTypeForwardCall
    );

    class CallInfoCommon : public SkinnyMsg
    {
    protected:
      CallInfoCommon(uint32_t id, PINDEX len, PINDEX extraSpace) : SkinnyMsg(id, len, extraSpace) { }
    public:
      virtual const PUInt32l & GetLineInstance() const = 0;
      virtual const PUInt32l & GetCallIdentifier() const = 0;
      virtual CallType GetType() const = 0;
      virtual const char * GetCalledPartyName() const = 0;
      virtual const char * GetCalledPartyNumber() const = 0;
      virtual const char * GetCallingPartyName() const = 0;
      virtual const char * GetCallingPartyNumber() const = 0;
      virtual const char * GetRedirectingPartyNumber() const = 0;

      virtual void PrintOn(ostream & strm) const;
    };

    OPAL_SKINNY_MSG2(CallInfoMsg,  CallInfoCommon, 0x008f, 0,
      char     m_callingPartyName[40];
      char     m_callingPartyNumber[24];
      char     m_calledPartyName[40];
      char     m_calledPartyNumber[24];
      PUInt32l m_lineInstance;
      PUInt32l m_callIdentifier;
      PUInt32l m_callType;
      char     m_originalCalledPartyName[40];
      char     m_originalCalledPartyNumber[24];
      char     m_lastRedirectingPartyName[40];
      char     m_lastRedirectingPartyNumber[24];
      PUInt32l m_originalCalledPartyRedirectReason;
      PUInt32l m_lastRedirectingReason;
      char     m_callingPartyVoiceMailbox[24];
      char     m_calledPartyVoiceMailbox[24];
      char     m_originalCalledPartyVoiceMailbox[24];
      char     m_lastRedirectingVoiceMailbox[24];
      PUInt32l m_callInstance;
      PUInt32l m_callSecurityStatus;
      PUInt32l m_partyPIRestrictionBits;

      virtual const PUInt32l & GetLineInstance() const { return m_lineInstance; }
      virtual const PUInt32l & GetCallIdentifier() const { return m_callIdentifier; }
      virtual CallType GetType() const { return (CallType)(uint32_t)m_callType; }
      virtual const char * GetCalledPartyName() const { return m_calledPartyName; }
      virtual const char * GetCalledPartyNumber() const { return m_calledPartyNumber; }
      virtual const char * GetCallingPartyName() const { return m_callingPartyName; }
      virtual const char * GetCallingPartyNumber() const { return m_callingPartyNumber; }
      virtual const char * GetRedirectingPartyNumber() const { return m_lastRedirectingPartyNumber; }
    );

    enum { CallInfo5MsgStringSpace = 200 };
    OPAL_SKINNY_MSG2(CallInfo5Msg, CallInfoCommon, 0x014a, CallInfo5MsgStringSpace,
      PUInt32l m_lineInstance;
      PUInt32l m_callIdentifier;
      PUInt32l m_callType;
      PUInt32l m_originalCalledPartyRedirectReason;
      PUInt32l m_lastRedirectingReason;
      PUInt32l m_callInstance;
      PUInt32l m_callSecurityStatus;
      PUInt32l m_partyPIRestrictionBits;
      char     m_strings[CallInfo5MsgStringSpace+11]; // Allow space for strings

      virtual const PUInt32l & GetLineInstance() const { return m_lineInstance; }
      virtual const PUInt32l & GetCallIdentifier() const { return m_callIdentifier; }
      virtual CallType GetType() const { return (CallType)(uint32_t)m_callType; }
      virtual const char * GetCalledPartyName() const { return GetStringByIndex(9); }
      virtual const char * GetCalledPartyNumber() const { return GetStringByIndex(1); }
      virtual const char * GetCallingPartyName() const { return GetStringByIndex(8); }
      virtual const char * GetCallingPartyNumber() const { return GetStringByIndex(0); }
      virtual const char * GetRedirectingPartyNumber() const { return GetStringByIndex(3); }

      protected:
        const char * GetStringByIndex(PINDEX idx) const;
    );

    enum RingType
    {
      eRingOff = 1,
      eRingInside,
      eRingOutside,
      eRingFeature
    };
    OPAL_SKINNY_MSG(SetRingerMsg, 0x0085,
      PUInt32l m_ringType;
      PUInt32l m_ringMode;
      PUInt32l m_lineInstance;
      PUInt32l m_callIdentifier;

      __inline RingType GetType() const { return (RingType)(uint32_t)m_ringType; }
      __inline bool IsForever() const { return m_ringMode == 1; }
      virtual void PrintOn(ostream & strm) const;
    );

    OPAL_SKINNY_MSG(OffHookMsg, 0x0006,
      PUInt32l m_lineInstance;
      PUInt32l m_callIdentifier;

      virtual void PrintOn(ostream & strm) const;
    );

    OPAL_SKINNY_MSG(OnHookMsg, 0x0007,
      PUInt32l m_lineInstance;
      PUInt32l m_callIdentifier;

      virtual void PrintOn(ostream & strm) const;
    );

    enum Tones
    {
      eToneSilence     = 0,
      eToneDial        = 33,
      eToneBusy        = 35,
      eToneAlert       = 36,
      eToneReorder     = 37,
      eToneCallWaiting = 45,
      eToneNoTone      = 0x7f
    };
    OPAL_SKINNY_MSG(StartToneMsg, 0x0082,
      PUInt32l m_tone;
      BYTE     m_unknown[4];
      PUInt32l m_lineInstance;
      PUInt32l m_callIdentifier;

      __inline Tones GetType() const { return (Tones)(uint32_t)m_tone; }
      virtual void PrintOn(ostream & strm) const;
    );

    OPAL_SKINNY_MSG(StopToneMsg, 0x0083,
      PUInt32l m_lineInstance;
      PUInt32l m_callIdentifier;

      virtual void PrintOn(ostream & strm) const;
    );

    OPAL_SKINNY_MSG(KeyPadButtonMsg, 0x0003,
      BYTE     m_dtmf;
      BYTE     m_padding[3];
      PUInt32l m_lineInstance;
      PUInt32l m_callIdentifier;

      virtual void PrintOn(ostream & strm) const;
    );

    P_DECLARE_STREAMABLE_ENUM(SoftKeyEvents,
      eSoftUnknown,
      eSoftKeyRedial,
      eSoftKeyNewCall,
      eSoftKeyHold,
      eSoftKeyTransfer,
      eSoftKeyCfwdall,
      eSoftKeyCfwdBusy,
      eSoftKeyCfwdNoAnswer,
      eSoftKeyBackspace,
      eSoftKeyEndcall,
      eSoftKeyResume,
      eSoftKeyAnswer,
      eSoftKeyInfo,
      eSoftKeyConf,
      eSoftKeyPark,
      eSoftKeyJoin,
      eSoftKeyMeetMe,
      eSoftKeyCallPickup,
      eSoftKeyGrpCallPickup,
      eSoftKeyDND,
      eSoftKeyDivert
    );
    OPAL_SKINNY_MSG(SoftKeyEventMsg, 0x0026,
      PUInt32l m_event;
      PUInt32l m_lineInstance;
      PUInt32l m_callIdentifier;

      __inline SoftKeyEvents GetEvent() const { return (SoftKeyEvents)(uint32_t)m_event; }
      virtual void PrintOn(ostream & strm) const;
    );

    OPAL_SKINNY_MSG(OpenReceiveChannelMsg, 0x0105,
      PUInt32l m_callIdentifier;
      PUInt32l m_passThruPartyId;
      PUInt32l m_msPerPacket;
      PUInt32l m_payloadCapability;
      PUInt32l m_echoCancelType;
      PUInt32l m_g723Bitrate;
      BYTE     m_unknown[68];

      virtual void PrintOn(ostream & strm) const;
    );

    OPAL_SKINNY_MSG(OpenReceiveChannelAckMsg, 0x0022,
      PUInt32l m_status;
      in_addr  m_ip;
      PUInt16l m_port;
      BYTE     m_padding[2];
      PUInt32l m_passThruPartyId;
      virtual void PrintOn(ostream & strm) const;
    );

    OPAL_SKINNY_MSG(CloseReceiveChannelMsg, 0x0106,
      PUInt32l m_callIdentifier;
      PUInt32l m_passThruPartyId;
      PUInt32l m_conferenceId2;

      virtual void PrintOn(ostream & strm) const;
    );

    OPAL_SKINNY_MSG(StartMediaTransmissionMsg, 0x008a,
      PUInt32l m_callIdentifier;
      PUInt32l m_passThruPartyId;
      in_addr  m_ip;
      PUInt16l m_port;
      BYTE     m_padding[2];
      PUInt32l m_msPerPacket;
      PUInt32l m_payloadCapability;
      PUInt32l m_precedence;
      PUInt32l m_silenceSuppression;
      PUInt32l m_maxFramesPerPacket;
      PUInt32l m_g723Bitrate;
      BYTE     m_unknown[68];

      virtual void PrintOn(ostream & strm) const;
    );

    OPAL_SKINNY_MSG(StopMediaTransmissionMsg, 0x008b,
      PUInt32l m_callIdentifier;
      PUInt32l m_passThruPartyId;
      PUInt32l m_conferenceId2;

      virtual void PrintOn(ostream & strm) const;
    );
#pragma pack()


    const PFilePath & GetSimulatedFarAudioFile() const { return m_simulatedFarAudioFile; }
    void SetSimulatedFarAudioFile(const PString str) { m_simulatedFarAudioFile = str; }
    const PFilePath & GetSimulatedNearAudioFile() const { return m_simulatedNearAudioFile; }
    void SetSimulatedNearAudioFile(const PString str) { m_simulatedNearAudioFile = str; }

    const PDirectory & GetSimulatedAudioFolder() const { return m_simulatedAudioFolder; }
    void SetSimulatedAudioFolder(const PString str) { m_simulatedAudioFolder = str; }

    PFilePath GetEndpointSimulatedAudioFile(const PString& name, unsigned sessionId) const;

    bool IsSecondaryAudioAlwaysSimulated() const { return m_secondaryAudioAlwaysSimulated; }
    void SetSecondaryAudioAlwaysSimulated(bool v) { m_secondaryAudioAlwaysSimulated = v; }

    void SetServerInterfaces(const PString & addresses) { m_serverInterfaces = OpalTransportAddressArray(addresses); }

  protected:
    template <class MSG> bool DelegateMsg(const PhoneDevice & client, const MSG & msg);

    typedef PDictionary<PString, PhoneDevice> PhoneDeviceDict;
    PhoneDeviceDict           m_phoneDevices;
    PDECLARE_MUTEX(m_phoneDevicesMutex);
    OpalTransportAddressArray m_serverInterfaces;
    PFilePath                 m_simulatedFarAudioFile;
    PFilePath                 m_simulatedNearAudioFile;
    PDirectory                m_simulatedAudioFolder;
    bool                      m_secondaryAudioAlwaysSimulated;
};


class OpalSkinnyConnection : public OpalRTPConnection
{
    PCLASSINFO(OpalSkinnyConnection, OpalRTPConnection);
  public:
    OpalSkinnyConnection(
      OpalCall & call,
      OpalSkinnyEndPoint & ep,
      OpalSkinnyEndPoint::PhoneDevice & client,
      unsigned callIdentifier,
      const PString & dialNumber,
      void * /*userData*/,
      unsigned options,
      OpalConnection::StringOptions * stringOptions
    );

    virtual bool IsNetworkConnection() const { return true; }

    virtual PBoolean SetUpConnection();

    virtual void OnReleased();

    virtual OpalMediaFormatList GetMediaFormats() const;

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

    virtual PBoolean SetConnected();

    virtual OpalMediaType::AutoStartMode GetAutoStart(
      const OpalMediaType & mediaType  
    ) const;

    virtual PString GetAlertingType() const;

    virtual void OnClosedMediaStream(
      const OpalMediaStream & stream     
    );

    virtual OpalTransportAddress GetRemoteAddress() const;

    virtual bool OnReceiveMsg(const OpalSkinnyEndPoint::CallStateMsg & msg);
    virtual bool OnReceiveMsg(const OpalSkinnyEndPoint::CallInfoMsg & msg);
    virtual bool OnReceiveMsg(const OpalSkinnyEndPoint::CallInfo5Msg & msg);
    virtual bool OnReceiveMsg(const OpalSkinnyEndPoint::SetRingerMsg & msg);
    virtual bool OnReceiveMsg(const OpalSkinnyEndPoint::StartToneMsg & msg);
    virtual bool OnReceiveMsg(const OpalSkinnyEndPoint::OpenReceiveChannelMsg & msg);
    virtual bool OnReceiveMsg(const OpalSkinnyEndPoint::CloseReceiveChannelMsg & msg);
    virtual bool OnReceiveMsg(const OpalSkinnyEndPoint::StartMediaTransmissionMsg & msg);
    virtual bool OnReceiveMsg(const OpalSkinnyEndPoint::StopMediaTransmissionMsg & msg);

  protected:
    bool OnReceiveCallInfo(const OpalSkinnyEndPoint::CallInfoCommon & msg);

    struct MediaInfo
    {
      MediaInfo(const OpalSkinnyEndPoint::OpenReceiveChannelMsg & msg);
      MediaInfo(const OpalSkinnyEndPoint::CloseReceiveChannelMsg & msg);
      MediaInfo(const OpalSkinnyEndPoint::StartMediaTransmissionMsg & msg);
      MediaInfo(const OpalSkinnyEndPoint::StopMediaTransmissionMsg & msg);

      bool operator<(const MediaInfo & other) const;

      bool                 m_receiver;
      uint32_t             m_passThruPartyId;
      uint32_t             m_payloadCapability;
      OpalTransportAddress m_mediaAddress;
      mutable unsigned     m_sessionId;
    };
    void OpenMediaChannel(const MediaInfo & info);
    void OpenSimulatedMediaChannel(const MediaInfo & info, const OpalMediaFormat & mediaFormat);
    void DelayCloseMediaStream(OpalMediaStreamPtr mediaStream);

    OpalSkinnyEndPoint & m_endpoint;
    OpalSkinnyEndPoint::PhoneDevice & m_phoneDevice;

    uint32_t m_lineInstance;
    uint32_t m_callIdentifier;
    PString  m_alertingType;
    bool     m_needSoftKeyEndcall;
    bool     m_remoteHold;

    OpalMediaFormatList m_remoteMediaFormats;
    std::set<MediaInfo> m_passThruMedia;
    std::set<unsigned>  m_simulatedTransmitters;
};


template <class MSG> bool OpalSkinnyEndPoint::DelegateMsg(const PhoneDevice & phone, const MSG & msg)
{
  PSafePtr<OpalSkinnyConnection> connection = phone.m_activeConnection;
  PTRACE_CONTEXT_ID_PUSH_THREAD(connection);
  return connection == NULL || !connection.SetSafetyMode(PSafeReadWrite) || connection->OnReceiveMsg(msg);
}


#endif // OPAL_SKINNY

#endif // OPAL_SKINNY_H