CPhone Class Reference

Description

IP Telephone.

Note: The instantiation of multiple instances is not fully supported in some backends.

Definition at line 236 of file phone.H.

#include "phone.H"

Public Member Functions
General ...
void	Iterate ()
	Iterate the backend and update the phone state; must be called regularly.
Setup ...
void	Setup (const char *agentName, int _mediaSelected, int withLogging, const char *tmpDir)
	Setup phone object. More...
bool	Register (const char *identity=NULL, const char *secret=NULL)
	Register phone with a registrar. More...
Actions ...
These are actions that can be initiated by the application. Unless a 'Get...' method is present in this section, the effect may not immediately visible, e.g. the phone state may change somewhat later and will be returned by the backend via the callback mechanisms below. By default, the functions return 'true' on success (= no immediate failure), otherwise they print a warning message and return 'false'.
bool	Dial (const char *url)
	Dial the number or URL. More...
bool	AcceptCall ()
	Green button on the phone: Accept an incoming call. More...
bool	Hangup ()
	Red button on the phone: Cancel a call or a dialing process. If there is a paused call, it will be resumed and become the active call again. More...
bool	CancelAllCalls ()
	Cancel all active calls, try to reach the idle state as soon as possible. More...
bool	PrepareTransfer ()
	Pause (hold) the current call and set phone into the state 'psTransferIdle' to initiate an attended transfer. For an unattended transfer, call CompleteTransfer() immediately after dialing (Dial()).
bool	CompleteTransfer ()
	Transfer the paused call to the active one (complete the transfer). If called when still dialing, the auto-pickup state is entered automatically.
bool	SendDtmf (const char *dtmfSequence)
	Send a sequence of DTMF characters.
Handling incoming calls ...
void	SetIncomingCallAction (EPhoneState _incomingAction)
	Set decision on what to do with an incoming call in form of a desired next state: More...
EPhoneState	GetIncomingCallAction ()
void	SetAutoAccept ()
void	SetAutoReject ()
void	SetManualAccept ()
Media selection ...
void	SelectMedia (unsigned selected, unsigned mask=pmAll)
unsigned	GetMediaSelected ()
void	SetMicOn (bool on)
bool	GetMicOn ()
void	SetCamOn (bool on)
bool	GetCamOn ()
State retrieval ...
These methods and callback functions are used to retrieve the actual state of the underlying phone. Each callback can alternatively be installed by either overloading a virtual method ( On...() ) or by passing a C function ( SetCb...() ) together with some arbitrary user data ('data').
EPhoneState	GetState ()
	Get current phone state.
virtual void	OnPhoneStateChanged (EPhoneState oldState)
void	SetCbPhoneStateChanged (void(*_cbPhoneStateChanged)(void *, EPhoneState), void *data=NULL)
	Callback on a phone state change; the second parameter is the previous state.
virtual void	OnInfo (const char *msg)
void	SetCbInfo (void(*_cbInfo)(void *, const char *), void *data=NULL)
	Callback on the receipt of a new info message (should be displayed on the UI).
virtual void	OnDtmfReceived (char dtmf)
void	SetCbDtmfReceived (void(*_cbDtmfReceived)(void *, char), void *data=NULL)
	Callback on the receipt of a DTMF character.
int	GetCallDuration (int callId=0)
	Get call duration in seconds. More...
const char *	GetPeerUrl (int callId=0)
	Get the URL of the peer. More...
Video stream retrieval ...
The backend should provide 2 video streams, referring to 'streamId' == 0/1: 0: Main video (to be displayed in a big frame, e.g. received video) 1: Small video (to be displayed in a small frame, e.g. a self-view)
TPhoneVideoFrame *	VideoLockFrame (int streamId)
	Lock the video stream and return info about the current picture. More...
void	VideoUnlock ()
	Unlock the video stream.
For internal use only...
The following methods must be considered 'protected' and are called by the respective backend callbacks (Blame the author for not adding tons of "friend" clauses instead...).
void	ReportState (EPhoneState _state)
void	ReportInfo (const char *fmt,...)
void *	GetLibData ()
const int	GetLibDataSize ()

Member Function Documentation

Setup()

void CPhone::Setup	(	const char *	agentName,
		int	_mediaSelected,
		int	withLogging,
		const char *	tmpDir
	)

Setup phone object.

Parameters

agentName	is the reference to the name of the phone agent. The pointer must remain valid for the life time of the object.
_mediaSelected	is set of initially enabled media.
withLogging	enables logging, and should be set to the 'envDebug' setting.
tmpDir	is the root temporary directory. It should be set to some path below EnvHome2lTmp(). To disallow the generation of temporary files (e.g. database for noise cancellation), NULL may be passed here.

A call to this function finally causes a "state changed" event from 'psNone' to 'psIdle'. If the callback handlers are set before, this can be caught for initialization purposes.

A registration does not happen automatically here. To register, call Register() afterwards.

Note: (2017-01-15) Persistent echo cancellation with Linphone requires a patched version of Linphone (see external/linphone).

Register()

bool CPhone::Register	(	const char *	identity = NULL,
		const char *	secret = NULL
	)

Register phone with a registrar.

Parameters

identity	is a string containing the user name and eventually domain of the identity, for example: "Joe Miller <joe@example.org>".
secret	is the password.

Both arguments are references and must remain valid for the lifetime of the object. If NULL is passed for the identity, the default/main account defined by 'phone.register' and 'phone.secret' is registered.

Dial()

bool CPhone::Dial

(

const char *

url

)

Dial the number or URL.

If PrepareTransfer() was called previously, an eventually existing call will be paused automatically and the new peer is called as a future destination.

Note: The caller must make sure that the audio/video devices is not opened before calling this method, since the phone library may use it from now.

AcceptCall()

bool CPhone::AcceptCall

(

)

Green button on the phone: Accept an incoming call.

Note: The caller must make sure that the audio/video devices is not opened before calling this method, since the phone library may use it from now.

Hangup()

bool CPhone::Hangup

(

)

Red button on the phone: Cancel a call or a dialing process. If there is a paused call, it will be resumed and become the active call again.

Note: The caller must not open the audio/video devices before a "device-permitting" state (e.g. 'psIdle') is reported again.

CancelAllCalls()

bool CPhone::CancelAllCalls

(

)

Cancel all active calls, try to reach the idle state as soon as possible.

Note: The caller must not open the audio/video devices before a "device-permitting" state (e.g. 'psIdle') is reported again.

SetIncomingCallAction()

void CPhone::SetIncomingCallAction ( EPhoneState  _incomingAction )

inline

Set decision on what to do with an incoming call in form of a desired next state:

• 'psRinging': let it ring (default mode)
• 'psInCall': automatically accept (e.g. for baby phone mode or for a door phone)
• others: reject call

Note: The caller must make sure that the audio/video devices are not opened before calling this method with argument 'psInCall'.

Definition at line 348 of file phone.H.

GetCallDuration()

int CPhone::GetCallDuration

(

int

callId = 0

)

Get call duration in seconds.

Parameters

callId

is 0 for the (last) active call, or 1 for the currently paused one.

GetPeerUrl()

const char * CPhone::GetPeerUrl

(

int

callId = 0

)

Get the URL of the peer.

Parameters

callId

is 0 for the (last) active call, or 1 for the currently paused one.

Note:

1. This method is not thread-safe (only call from main thread / same thread as all other methods of all other 'CPhone' objects).
2. The returned pointer is valid until the next call of this method (for any object!).

VideoLockFrame()

TPhoneVideoFrame * CPhone::VideoLockFrame

(

int

streamId

)

Lock the video stream and return info about the current picture.

The lock must be held as long as the return value is used and must be unlocked even if 'NULL' is returned. Also resets the internal "changed" flag automatically.

---

The documentation for this class was generated from the following file:

• common/phone.H