frame.h

Go to the documentation of this file.

/*
 *
 * Inter Asterisk Exchange 2
 * 
 * Open Phone Abstraction Library (OPAL)
 *
 * Define the classes that carry information over the ethernet.
 *
 * Copyright (c) 2005 Indranet Technologies 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 Indranet Technologies Ltd.
 *
 * The author of this code is Derek J Smithies
 *
 *  $Log: frame.h,v $
 *  Revision 1.12  2007/09/05 04:04:35  csoutheren
 *  Fixed spelling mistakes
 *
 *  Revision 1.11  2007/04/19 06:17:21  csoutheren
 *  Fixes for precompiled headers with gcc
 *
 *  Revision 1.10  2007/01/23 02:08:25  dereksmithies
 *  Handle Vnak frames correctly. handle iseqno and oseqno correctly.
 *
 *  Revision 1.9  2007/01/17 03:48:13  dereksmithies
 *  Tidy up comments, remove leaks, improve reporting of packet types.
 *
 *  Revision 1.8  2007/01/16 03:17:42  dereksmithies
 *  tidyup of comments. Remove unused variables.
 *  Guarantee that media frames are sent with a monotonically increasing timestamp
 *
 *  Revision 1.7  2006/08/09 03:46:39  dereksmithies
 *  Add ability to register to a remote Asterisk box. The iaxProcessor class is split
 *  into a callProcessor and a regProcessor class.
 *  Big thanks to Stephen Cook, (sitiveni@gmail.com) for this work.
 *
 *  Revision 1.6  2005/08/26 03:07:38  dereksmithies
 *  Change naming convention, so all class names contain the string "IAX2"
 *
 *  Revision 1.5  2005/08/25 03:26:06  dereksmithies
 *  Add patch from Adrian Sietsma to correctly set the packet timestamps under windows.
 *  Many thanks.
 *
 *  Revision 1.4  2005/08/24 04:56:25  dereksmithies
 *  Add code from Adrian Sietsma to send FullFrameTexts and FullFrameDtmfs to
 *  the remote end.  Many Thanks.
 *
 *  Revision 1.3  2005/08/24 01:38:38  dereksmithies
 *  Add encryption, iax2 style. Numerous tidy ups. Use the label iax2, not iax
 *
 *  Revision 1.2  2005/08/04 08:14:17  rjongbloed
 *  Fixed Windows build under DevStudio 2003 of IAX2 code
 *
 *  Revision 1.1  2005/07/30 07:01:32  csoutheren
 *  Added implementation of IAX2 (Inter Asterisk Exchange 2) protocol
 *  Thanks to Derek Smithies of Indranet Technologies Ltd. for
 *  writing and contributing this code
 *
 *
 *
 *
 */

#ifndef FRAME_H
#define FRAME_H

#ifndef _PTLIB_H
#include <ptlib.h>
#endif

#include <iax2/ies.h>
#include <iax2/remote.h>

#include <ptlib/sockets.h>

#ifdef P_USE_PRAGMA
#pragma interface
#endif

class IAX2Frame;
class IAX2FrameList;
class IAX2FullFrame;
class IAX2FullFrameCng;
class IAX2FullFrameDtmf;
class IAX2FullFrameHtml;
class IAX2FullFrameImage;
class IAX2FullFrameNull;
class IAX2FullFrameProtocol;
class IAX2FullFrameSessionControl;
class IAX2FullFrameText;
class IAX2FullFrameVideo;
class IAX2FullFrameVoice;
class IAX2EndPoint;
class IAX2Processor;
class IAX2CallProcessor;
class IAX2IeList;
class IAX2MiniFrame;
class IAX2Transmitter;



class IAX2Frame :  public PObject
{
  PCLASSINFO(IAX2Frame, PObject);
 public:
  IAX2Frame(IAX2EndPoint &_endpoint);
  
  virtual ~IAX2Frame();
  
  BOOL ReadNetworkPacket(PUDPSocket &sock);
  
  virtual BOOL ProcessNetworkPacket();
  
  virtual BOOL IsFullFrame();
  
  BOOL IsVideo() const;
  
  BOOL IsAudio() const;

  virtual BYTE *GetMediaDataPointer() { return data.GetPointer(); }
  
  virtual PINDEX GetMediaDataSize() { return DataSize();}
  
  PINDEX DataSize() { return data.GetSize(); }
  
  IAX2Remote & GetRemoteInfo() { return remote; }
  
  const BYTE * GetDataPointer() { return data + currentReadIndex; }
  
  IAX2Frame * BuildAppropriateFrameType(IAX2Encryption &encryptionInfo);

  IAX2Frame * BuildAppropriateFrameType();

  PINDEX   GetUnReadBytes() { return data.GetSize() - currentReadIndex; }
  
  virtual BOOL WriteHeader() { return FALSE; }
  
  virtual BOOL TransmitPacket(PUDPSocket &sock);
  
  virtual void PrintOn(ostream & strm) const;
  
  static DWORD CalcTimeStamp(const PTimeInterval & callStartTick);

  virtual void BuildTimeStamp(const PTimeInterval & callStartTick);
  
  IAX2EndPoint & GetEndpoint() { return endpoint; }
  
  PString IdString() const { return PString("FR-ID#") + PString(frameIndex); }
  
  
  DWORD  GetTimeStamp() { return timeStamp; }
  
  virtual BOOL CallMustBeActive() { return TRUE; }     
  
  enum IAX2FrameType {
    undefType        = 0,     
    dtmfType         = 1,     
    voiceType        = 2,     
    videoType        = 3,     
    controlType      = 4,     
    nullType         = 5,     
    iax2ProtocolType = 6,     
    textType         = 7,     
    imageType        = 8,     
    htmlType         = 9,     
    cngType          = 10,    
    numFrameTypes    = 11     
  };
  
  IAX2FrameType GetFrameType() { return frameType; }
    
  virtual void InitialiseHeader(IAX2Processor * /*processor*/) { }
  
  BOOL CanRetransmitFrame() const {return canRetransmitFrame; } 
  
  PString GetConnectionToken() const { return connectionToken; }

  void SetConnectionToken(PString newToken) { connectionToken = newToken; } 

  void BuildConnectionTokenId();

  BOOL EncryptContents(IAX2Encryption &encData);

  virtual PINDEX GetEncryptionOffset();

 protected:

  BOOL DecryptContents(IAX2Encryption & encryption);

  IAX2Remote  remote;
  
  IAX2FrameType frameType;
  
  BOOL          Read1Byte(BYTE & res);
  
  BOOL          Read2Bytes(PINDEX & res);
  
  BOOL          Read2Bytes(WORD & res);
  
  BOOL          Read4Bytes(DWORD & res);
  
  void          Write1Byte(BYTE newVal);
  
  void          Write1Byte(PINDEX newVal);
  
  void          Write2Bytes(PINDEX newVal);
  
  void          Write4Bytes(unsigned int newVal);
  
  void          ZeroAllValues();
  
  IAX2EndPoint      & endpoint;
  
  PBYTEArray         data;
  
  BOOL               isFullFrame;
  
  BOOL               isVideo;
  
  BOOL               isAudio;
  
  PINDEX               currentReadIndex;  
  
  PINDEX               currentWriteIndex;  
  
  DWORD                timeStamp;  
  
  int                frameIndex;
  
  BOOL               canRetransmitFrame;

  PString            connectionToken;

  DWORD presetTimeStamp;
};


class IAX2MiniFrame : public IAX2Frame
{
  PCLASSINFO(IAX2MiniFrame, IAX2Frame);
 public:
  IAX2MiniFrame(IAX2Frame & srcFrame);
  
  IAX2MiniFrame(IAX2EndPoint & _endpoint); 
  
  IAX2MiniFrame(IAX2Processor * con, PBYTEArray &sound, BOOL isAudio, DWORD usersTimeStamp = 0);

  virtual ~IAX2MiniFrame();
  
  virtual BOOL ProcessNetworkPacket();
  
  virtual BOOL WriteHeader();
  
  virtual void PrintOn(ostream & strm) const;
  
  virtual BYTE *GetMediaDataPointer();
  
  virtual PINDEX GetMediaDataSize();
  
  void AlterTimeStamp(PINDEX newValue);
  
  virtual void InitialiseHeader(IAX2Processor *processor);
  
  virtual PINDEX GetEncryptionOffset();

 protected:
  void ZeroAllValues();
};


class IAX2FullFrame : public IAX2Frame
{
  PCLASSINFO(IAX2FullFrame, IAX2Frame);
 public:
  IAX2FullFrame(IAX2Frame & srcFrame);
  
  IAX2FullFrame(IAX2EndPoint  &_endpoint);
  
  virtual ~IAX2FullFrame();
  
  BOOL IsAckFrame() { return isAckFrame; }
  
  BOOL IsPingFrame();

  BOOL IsNewFrame();

  BOOL IsLagRqFrame();

  BOOL IsLagRpFrame();

  BOOL IsPongFrame();

  BOOL IsAuthReqFrame();

  BOOL IsVnakFrame();
  
  BOOL IsRegReqFrame();
  
  BOOL IsRegAuthFrame();
  
  BOOL IsRegAckFrame();  
  
  BOOL IsRegRelFrame();
  
  BOOL IsRegRejFrame();

  BOOL FrameIncrementsInSeqNo();

  virtual BOOL IsFullFrame() { return TRUE; }  
  
  BOOL IsHangupFrame();

  void ZeroAllValues();
  
  virtual BOOL ProcessNetworkPacket();
  
  virtual BOOL TransmitPacket(PUDPSocket &sock);
  
  PString GetFullFrameName() const;
  
  virtual PString GetSubClassName() const
    { return PString(" subclass=") + PString(subClass); }
  
  void MarkDeleteNow();
  
  void MarkVnakSendNow();

  virtual BYTE *GetMediaDataPointer();
  
  virtual PINDEX GetMediaDataSize();
  
  PINDEX GetSubClass() const { return subClass; }
  
  void SetSubClass(PINDEX newValue) { subClass = newValue;}
  
  virtual BOOL WriteHeader();
  
  void ModifyFrameHeaderSequenceNumbers(PINDEX inNo, PINDEX outNo);

  void ModifyFrameTimeStamp(PINDEX newTimeStamp);

  virtual BOOL InformationElementsPresent() { return FALSE; }  
  
  BOOL  SendFrameNow() { return sendFrameNow; }
  
  BOOL  DeleteFrameNow() { return deleteFrameNow; }
  
  IAX2SequenceNumbers & GetSequenceInfo() { return sequence; }
  
  virtual void PrintOn(ostream & strm) const;
  
  void MarkAsResent();
  
  BOOL operator *= (IAX2FullFrame & other);
  
  enum ConnectionRequired {
    callActive,      
    callIrrelevant   
  };
  
  virtual BYTE GetFullFrameType() { return 0; }

  virtual PINDEX GetEncryptionOffset() { return 4; }
  
 protected:
  virtual BOOL CallMustBeActive() { return callMustBeActive; }
  
  void UnCompressSubClass(BYTE a);
  
  int  CompressSubClass();
  
  void ClearListFlags();
  
  virtual void InitialiseHeader(IAX2Processor *processor);
  
#ifdef DOC_PLUS_PLUS

  void OnTransmissionTimeout(PTimer &, INT);
#else
  PDECLARE_NOTIFIER(PTimer, IAX2FullFrame, OnTransmissionTimeout);
#endif

  PTimer transmissionTimer;
  
  PINDEX subClass;
  
  PTimeInterval retryDelta;     
  
  PTimeInterval timeOffset;     
  
  PINDEX       retries;        
  
  enum RetryTime {
    minRetryTime = 500,    
    maxRetryTime = 010000, 
    maxRetries   = 10,     
  };
  
  IAX2SequenceNumbers sequence;
  
  BOOL         sendFrameNow;   
  
  BOOL         deleteFrameNow; 
  
  BOOL         packetResent;   
  
  BOOL callMustBeActive;
  
  BOOL isAckFrame;  
};


class IAX2FullFrameDtmf : public IAX2FullFrame
{
  PCLASSINFO(IAX2FullFrameDtmf, IAX2FullFrame);
 public:
  IAX2FullFrameDtmf(IAX2Frame & srcFrame);

  IAX2FullFrameDtmf(IAX2FullFrame & srcFrame);
  
  IAX2FullFrameDtmf(IAX2Processor *processor, 
                    char  subClassValue       
                    );
  
  IAX2FullFrameDtmf(IAX2Processor *processor, 
                PString  subClassValue    
                );
  
  
  virtual PString GetSubClassName() const; 
  
  enum DtmfSc {
    dtmf0 = 48,     
    dtmf1 = 49,     
    dtmf2 = 50,     
    dtmf3 = 51,     
    dtmf4 = 52,     
    dtmf5 = 53,     
    dtmf6 = 54,     
    dtmf7 = 55,     
    dtmf8 = 56,     
    dtmf9 = 57,     
    dtmfA = 65,     
    dtmfB = 66,     
    dtmfC = 67,     
    dtmfD = 68,     
    dtmfStar = 42,  
    dtmfHash = 35   
  };
  
  virtual BYTE GetFullFrameType() { return dtmfType; }
  
 protected:
};


class IAX2FullFrameVoice : public IAX2FullFrame
{
  PCLASSINFO(IAX2FullFrameVoice, IAX2FullFrame);
 public:
  
  IAX2FullFrameVoice(IAX2Frame & srcFrame);
  
  IAX2FullFrameVoice(IAX2FullFrame & srcFrame);
  
  IAX2FullFrameVoice(IAX2CallProcessor *processor, PBYTEArray &sound, 
                 PINDEX usersTimeStamp = 0);
  
  virtual ~IAX2FullFrameVoice();

  virtual PString GetSubClassName() const;
  
  static PString GetSubClassName(unsigned short testValue)
     { return GetSubClassName((unsigned int) testValue); }

  static PString GetSubClassName(unsigned int testValue);
  
  static PString GetOpalNameOfCodec(PINDEX testValue);
  
  static PString GetSubClassName(int testValue) 
    { return GetSubClassName((unsigned short) testValue); }
  
  static unsigned short OpalNameToIax2Value(const PString opalName);

  enum AudioSc {
    g7231    = 1,         
    gsm      = 2,         
    g711ulaw = 4,         
    g711alaw = 8,         
    mp3      = 0x10,      
    adpcm    = 0x20,      
    pcm      = 0x40,      
    lpc10    = 0x80,      
    g729     = 0x100,     
    speex    = 0x200,     
    ilbc     = 0x400,     
    supportedCodecs = 11  
  };
  
  virtual BYTE GetFullFrameType() { return voiceType; }
};

class IAX2FullFrameVideo : public IAX2FullFrame
{
  PCLASSINFO(IAX2FullFrameVideo, IAX2FullFrame);
 public:
  
  IAX2FullFrameVideo(IAX2Frame & srcFrame);
  
  IAX2FullFrameVideo(IAX2FullFrame & srcFrame);
  
  virtual PString GetSubClassName() const;
  
  enum VideoSc {
    jpeg  = 0x10000,   
    png   = 0x20000,   
    h261  = 0x40000,   
    h263  = 0x80000    
  };
  
  virtual BYTE GetFullFrameType() { return videoType; }
 protected:
};


class IAX2FullFrameSessionControl : public IAX2FullFrame
{
  PCLASSINFO(IAX2FullFrameSessionControl, IAX2FullFrame);
 public:
  
  enum SessionSc {
    hangup          = 1,     
    ring            = 2,     
    ringing         = 3,     
    answer          = 4,     
    busy            = 5,     
    tkoffhk         = 6,     
    offhook         = 7,     
    congestion      = 8,     
    flashhook       = 9,     
    wink            = 10,    
    option          = 11,    
    keyRadio        = 12,    
    unkeyRadio      = 13,    
    callProgress    = 14,    
    callProceeding  = 15,    
    callOnHold      = 16,    
    callHoldRelease = 17,    
    stopSounds      = 255    
  };
  
  
  
  IAX2FullFrameSessionControl(IAX2Frame & srcFrame);
  
  IAX2FullFrameSessionControl(IAX2FullFrame & srcFrame);
  
  IAX2FullFrameSessionControl(IAX2Processor *processor, 
                          PINDEX subClassValue
                          );
  
  IAX2FullFrameSessionControl(IAX2Processor *processor,     
                          SessionSc subClassValue 
                          );
  
  virtual ~IAX2FullFrameSessionControl() { }

  virtual PString GetSubClassName() const;
  
  virtual BYTE GetFullFrameType() { return controlType; }
  
 protected:
};


class IAX2FullFrameNull : public IAX2FullFrame
{
  PCLASSINFO(IAX2FullFrameNull, IAX2FullFrame);
 public:
  IAX2FullFrameNull(IAX2EndPoint & endpoint) : IAX2FullFrame(endpoint)   { }
  
  IAX2FullFrameNull(IAX2Frame & srcFrame);
  
  IAX2FullFrameNull(IAX2FullFrame & srcFrame);
  
  virtual PString GetSubClassName() const { return  PString(""); }
  
  virtual BYTE GetFullFrameType() { return nullType; }
  
 protected:
};


class IAX2FullFrameProtocol : public IAX2FullFrame
{
  PCLASSINFO(IAX2FullFrameProtocol, IAX2FullFrame);
 public:
  
  enum ProtocolSc {
    cmdNew       =  1,       
    cmdPing      =  2,       
    cmdPong      =  3,       
    cmdAck       =  4,       
    cmdHangup    =  5,       
    cmdReject    =  6,       
    cmdAccept    =  7,       
    cmdAuthReq   =  8,       
    cmdAuthRep   =  9,       
    cmdInval     =  10,      
    cmdLagRq     =  11,      
    cmdLagRp     =  12,      
    cmdRegReq    =  13,      
    cmdRegAuth   =  14,      
    cmdRegAck    =  15,      
    cmdRegRej    =  16,      
    cmdRegRel    =  17,      
    cmdVnak      =  18,      
    cmdDpReq     =  19,      
    cmdDpRep     =  20,      
    cmdDial      =  21,      
    cmdTxreq     =  22,      
    cmdTxcnt     =  23,      
    cmdTxacc     =  24,      
    cmdTxready   =  25,      
    cmdTxrel     =  26,      
    cmdTxrej     =  27,      
    cmdQuelch    =  28,      
    cmdUnquelch  =  29,      
    cmdPoke      =  30,      
    cmdPage      =  31,      
    cmdMwi       =  32,      
    cmdUnsupport =  33,      
    cmdTransfer  =  34,      
    cmdProvision =  35,      
    cmdFwDownl   =  36,      
    cmdFwData    =  37       
  };
  
  IAX2FullFrameProtocol(IAX2Frame & srcFrame);
  
  IAX2FullFrameProtocol(IAX2FullFrame & srcFrame);
  
  IAX2FullFrameProtocol(IAX2Processor *processor,         
                    PINDEX subClassValue,            
                    ConnectionRequired needCon = IAX2FullFrame::callActive
                    );
  
  IAX2FullFrameProtocol(IAX2Processor *processor,         
                    ProtocolSc  subClassValue,       
                    ConnectionRequired needCon=IAX2FullFrame::callActive 
                    );
  
  IAX2FullFrameProtocol(IAX2Processor *processor,         
                    ProtocolSc  subClassValue,       
                    IAX2FullFrame *inReplyTo,            
                    ConnectionRequired needCon = IAX2FullFrame::callActive
                    );
  
  virtual ~IAX2FullFrameProtocol();
  
  void SetRetransmissionRequired();
  
  virtual BOOL InformationElementsPresent() { return !ieElements.IsEmpty(); }
  
  ProtocolSc GetSubClass() const { return (ProtocolSc) subClass; }

  virtual PString GetSubClassName() const; 

  static PString GetSubClassName(PINDEX t);
  
  IAX2Ie *GetIeAt(PINDEX i) {      return ieElements.GetIeAt(i); }
  
  void AppendIe(IAX2Ie *newElement) { ieElements.AppendIe(newElement); }
  
  void WriteIeAsBinaryData();
  
  void CopyDataFromIeListTo(IAX2IeData &res);
  
  void GetRemoteCapability(unsigned int & capability, unsigned int & preferred);

  virtual BYTE GetFullFrameType() { return iax2ProtocolType; }
  
  virtual void PrintOn(ostream & strm) const;

 protected:
  
  BOOL ReadInformationElements();
  
  IAX2IeList ieElements;

#if PTRACING
    friend ostream & operator<<(ostream & o, ProtocolSc t);
#endif
};


class IAX2FullFrameText : public IAX2FullFrame
{
  PCLASSINFO(IAX2FullFrameText, IAX2FullFrame);
 public:

  IAX2FullFrameText(IAX2Processor *processor,       
                const PString&  textValue
                );
  
  IAX2FullFrameText(IAX2Frame & srcFrame);
  
  IAX2FullFrameText(IAX2FullFrame & srcFrame);
  
  virtual PString GetSubClassName() const;
  
  virtual BYTE GetFullFrameType() { return textType; }

  PString GetTextString() const;

 protected:

  PString internalText;
};

class IAX2FullFrameImage : public IAX2FullFrame
{
  PCLASSINFO(IAX2FullFrameImage, IAX2FullFrame);
 public:
  
  IAX2FullFrameImage(IAX2Frame & srcFrame);
  
  IAX2FullFrameImage(IAX2FullFrame & srcFrame);
  
  virtual PString GetSubClassName() const;
  
  virtual BYTE GetFullFrameType() { return imageType; }
 protected:
};


class IAX2FullFrameHtml : public IAX2FullFrame
{
  PCLASSINFO(IAX2FullFrameHtml, IAX2FullFrame);
 public:
  
  IAX2FullFrameHtml(IAX2Frame & srcFrame);
  
  IAX2FullFrameHtml(IAX2FullFrame & srcFrame);
  
  virtual PString GetSubClassName() const;
  
  virtual BYTE GetFullFrameType() { return htmlType; }
 protected:
};


class IAX2FullFrameCng : public IAX2FullFrame
{
  PCLASSINFO(IAX2FullFrameCng, IAX2FullFrame);
 public:
  
  IAX2FullFrameCng(IAX2Frame & srcFrame);
  
  IAX2FullFrameCng(IAX2FullFrame & srcFrame);
  
  virtual PString GetSubClassName() const;
  
  virtual BYTE GetFullFrameType() { return cngType; }
 protected:
};


PDECLARE_LIST (IAX2FrameList, IAX2Frame *)
#ifdef DOC_PLUS_PLUS     //This makes emacs bracket matching code happy.

class IAX2FrameList : public IAX2Frame *  
{
#endif
 public:
  ~IAX2FrameList();
  
  void ReportList();
  
  IAX2Frame *GetLastFrame();
  
  void Initialise() {  DisallowDeleteObjects(); }
    
  BOOL Empty() { return GetSize() == 0; }
  
  void GrabContents(IAX2FrameList &src);
  
  void DeleteMatchingSendFrame(IAX2FullFrame *reply);

  void SendVnakRequestedFrames(IAX2FullFrameProtocol &src);

  void AddNewFrame(IAX2Frame *src);
  
  void GetResendFramesDeleteOldFrames(IAX2FrameList & framesToSend);
  
  virtual PINDEX GetSize() { PWaitAndSignal m(mutex); return PAbstractList::GetSize(); }
  
  void MarkAllAsResent();
  
 protected:
  virtual PINDEX GetEntries() { return PAbstractList::GetSize(); }
  
  PMutex mutex;
};




#endif // FRAME_H
/* The comment below is magic for those who use emacs to edit this file. */
/* With the comment below, the tab key does auto indent to 2 spaces.     */

/*
 * Local Variables:
 * mode:c
 * c-file-style:linux
 * c-basic-offset:2
 * End:
 */

---