phone.H

Go to the documentation of this file.

/*
 *  This file is part of the Home2L project.
 *
 *  (C) 2015-2021 Gundolf Kiefer
 *
 *  Home2L is free software: you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation, either version 3 of the License, or
 *  (at your option) any later version.
 *
 *  Home2L is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with Home2L. If not, see <https://www.gnu.org/licenses/>.
 *
 */
 
 
#ifndef _PHONE_
#define _PHONE_
 
 
/* Unfortunately, 'liblinphone' and friends make some definitions (e.g. for bool)
 * that conflict with other libraries and the main program. Hence, this module also acts
 * as a demilitarized zone. The header must not include any home2l-related basic headers.
 */
 
 
#include <stdint.h>
#include <pthread.h>
 
 
 
 
// *************************** Environment settings ****************************
 
 
// (read-only; primarily needed by the phone drivers themselves)
extern const char *envPhoneLinphonerc;
 
extern int envPhoneSipPort;
 
extern const char *envPhoneAudioDriver;
extern const char *envPhoneAudioDevice;
extern const char *envPhoneAudioInDevice;
extern const char *envPhoneAudioOutDevice;
extern float envPhoneAudioInGain;
extern float envPhoneAudioOutGain;
extern const char *envPhoneAudioCodec;
 
extern int envPhoneEchoTail;
extern int envPhoneEchoAlgo;
extern int envPhoneEchoAggressiveness;
extern bool envPhoneEchoNoiseSuppression;
 
extern const char *envPhoneVideoDriver;
extern const char *envPhoneVideoDevice;
extern const char *envPhoneVideoCodec;
 
extern const char *envPhoneRegister;
extern const char *envPhoneSecret;
 
extern const char *envPhoneRingbackFile;
extern const char *envPhoneRingbackFileKey;
extern float envPhoneRingbackLevel;
 
extern int envPhoneRotation;
 
 
 
 
 
// *************************** Video driver(s) *********************************
 
 
enum EPhoneVideoFormat {
  pvfNone = 0,
  pvfABGR8888,
  pvfBGR24,
  pvfARGB8888,
  pvfRGB24,
  pvfYUY2,
  pvfUYVY,
  pvfYVYU,
  pvfIYUV,
  pvfYV12
};
 
 
const char *StrPhoneVideoFormat (EPhoneVideoFormat x);
 
 
struct TPhoneVideoFrame {
  bool changed;              
 
  EPhoneVideoFormat format;  
  int w, h;                  
 
  uint8_t *data;                      
  int pitch;                          
 
  uint8_t *planeY, *planeU, *planeV;  
  int pitchY, pitchU, pitchV;         
};
 
 
static inline void PhoneVideoFrameInit (TPhoneVideoFrame *vf) {
  vf->changed = false;
 
  vf->format = pvfNone;
  vf->w = vf->h = 0;
 
  vf->data = NULL;
  vf->pitch = 0;
 
  vf->planeY = vf->planeU = vf->planeV = NULL;
  vf->pitchY = vf->pitchU = vf->pitchV = 0;
}
 
 
 
 
 
// *************************** CPhone ******************************************
 
// The class 'CPhone' represents a telephone. It contains two "Call"
// objects (#0 and #1). This is to support the following scenarios:
//
// a) Simple calls: only call #0 is used, #1 remains inactive.
//
// b) Transfer calls: #0 is the new call (or none), #1 the paused one.
//    Swapping between slots #0 and #1 happens on pausing/resuming.
//
// c) Camera preview for the door phone using a second call is presently
//    unsupported.
//    Current solution for door cam: Use primary call (no second call),
//    accept with mic muted. Drawback: Visitor recognizes accept action.
//
// d) Machines with multiple logical phones (door/gate phone) may use multiple
//    'CPhone' objects.
//
// NOTE on the use of audio / camera devices by other program modules / threads
// (e.g. application-programmed ringing, music playback):
//
// 1. To avoid conflicts, other modules must ensure that during the invocation
//    of any action ('Dial', 'AcceptCall', enabling auto-acceptance),
//    such devices are closed by the other modules.
//
// 2. Devices may be used by the other modules only after a "device-permitting"
//    state has been reported again via 'ReportState ()'. The "device-permitting"
//    states are: 'psIdle', 'psRinging'.
//
// To avoid race conditions, the following contract applies:
// - After returning from 'CPhone::Dial ()', the state is already 'psDialing'
//   (i.e. 'ReportState ()' is called from 'CPhone::Dial ()').
// - 'AcceptCall ()' is only called when in state 'psRinging'.
// - If 'SetIncomingCallAction (psInCall)' is called, the application does
//   not use any device at all.
 
 
enum EPhoneState {
  psNone = 0,             
  psIdle,                 
  psDialing,              
  psRinging,              
  psInCall,               
  psTransferIdle,         
  psTransferDialing,      
  psTransferAutoComplete, 
  psTransferInCall        
};
 
 
static inline bool PhoneStateIsDevicePermitting (EPhoneState s) { return s == psIdle || s == psRinging; }
 
 
enum EPhoneMedia {
  pmNone = 0,         
  pmAudioIn = 1,      
  pmAudioOut = 2,     
  pmAudio = 3,        
  pmVideoIn = 4,      
  pmVideoOut = 8,     
  pmVideo = 12,       
  pmAll = 15          
};
#define pmOff pmNone
#define pmOn pmAll
 
 
class CPhone {
  public:
    CPhone () { Init (); }
    ~CPhone () { Done (); }
    void Init ();
    void Done ();
 
 
    void Iterate ();    
 
 
 
 
    void Setup (const char *agentName, int _mediaSelected, int withLogging,
                const char *tmpDir);
 
    bool Register (const char *identity = NULL, const char *secret = NULL);
 
 
 
 
    bool Dial (const char *url);
    bool AcceptCall ();
    bool Hangup ();
    bool CancelAllCalls ();
 
    bool PrepareTransfer ();
    bool CompleteTransfer ();
 
    bool SendDtmf (const char *dtmfSequence);
 
 
 
 
    void SetIncomingCallAction (EPhoneState _incomingAction) { incomingAction = _incomingAction; }
    EPhoneState GetIncomingCallAction () { return incomingAction; }
 
    void SetAutoAccept () { SetIncomingCallAction (psInCall); }
    void SetAutoReject () { SetIncomingCallAction (psIdle); }
    void SetManualAccept () { SetIncomingCallAction (psRinging); }
 
 
 
 
    void SelectMedia (unsigned selected, unsigned mask = pmAll);
    unsigned GetMediaSelected () { return mediaSelected; }
 
    void SetMicOn (bool on) { SelectMedia (on ? pmOn : pmOff, pmAudioIn); }
    bool GetMicOn () { return GetMediaSelected () & pmAudioIn ? true : false; }
    void SetCamOn (bool on) { SelectMedia (on ? pmOn : pmOff, pmVideoIn); }
    bool GetCamOn () { return GetMediaSelected () & pmVideoIn ? true : false; }
 
 
 
 
    // Phone state...
    EPhoneState GetState () { return state; }   
 
    // Callbacks...
    virtual void OnPhoneStateChanged (EPhoneState oldState);
    void SetCbPhoneStateChanged (void (*_cbPhoneStateChanged) (void *, EPhoneState), void *data = NULL) { cbPhoneStateChanged = _cbPhoneStateChanged; cbPhoneStateChangedData = data; }
 
    virtual void OnInfo (const char *msg);
    void SetCbInfo (void (*_cbInfo) (void *, const char *), void *data = NULL) { cbInfo = _cbInfo; cbInfoData = data; }
 
    virtual void OnDtmfReceived (char dtmf);
    void SetCbDtmfReceived (void (*_cbDtmfReceived) (void *, char), void *data = NULL) { cbDtmfReceived = _cbDtmfReceived; cbDtmfReceivedData = data; }
 
    // Information...
    int GetCallDuration (int callId = 0);
    const char *GetPeerUrl (int callId = 0);
 
 
 
    TPhoneVideoFrame *VideoLockFrame (int streamId);
    void VideoUnlock ();
 
 
    void ReportState (EPhoneState _state);
    void ReportInfo (const char *fmt, ...);
    void *GetLibData () { return libData; }
    const int GetLibDataSize () { return sizeof (libData); }
 
  protected:
 
    // Various state fields...
    EPhoneState state;
    int mediaSelected;
    EPhoneState incomingAction;
 
    // Callbacks...
    void *cbPhoneStateChangedData, *cbInfoData, *cbDtmfReceivedData;
    void (*cbPhoneStateChanged) (void *, EPhoneState);
    void (*cbInfo) (void *, const char *);
    void (*cbDtmfReceived) (void *, char);
 
    // Video stream...
    TPhoneVideoFrame picInfo;   // contains 'updated' field
 
    // Library-specific data...
#define LIBDATA_SIZE 64
    uint8_t libData [LIBDATA_SIZE];
};
 
 
 
 
#endif