source: verona/phapi/phapi.h @ 138:efddf6e11c3c

Last change on this file since 138:efddf6e11c3c was 138:efddf6e11c3c, checked in by laurent, 2 years ago

bug fix : media accessors
File size: 42.4 KB
Line 
1#ifndef __PHAPI_H__
2#define __PHAPI_H__ 1
3/*
4  The phapi module implements simple interface for eXosip stack
5  Copyright (C) 2004  Vadim Lebedev  <vadim@mbdsys.com>
6 
7  This library is free software; you can redistribute it and/or
8  modify it under the terms of the GNU Lesser General Public
9  License as published by the Free Software Foundation; either
10  version 2.1 of the License, or (at your option) any later version.
11 
12  This library is distributed in the hope that it will be useful,
13  but WITHOUT ANY WARRANTY; without even the implied warranty of
14  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
15  Lesser General Public License for more details.
16 
17  You should have received a copy of the GNU Lesser General Public
18  License along with this library; if not, write to the Free Software
19  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
20*/
21
22/**
23 * @file phapi.h
24 * @brief softphone  API
25 *
26 * phoneapi is a library providing simplified api to create VOIP sessions
27 * using eXosip library oSIP stack and oRTP stack
28 * <P>
29 */
30
31/**
32 * @defgroup phAPI  Phone API
33 * @{
34 * 
35 *  From the perspecitve of the phApi client the call can be in the following states:
36 *   
37 *   [INCOMING], [ACCEPTING], [OUTGOING], [ESTABLISHED], [ONHOLD], [CLOSED]
38 *
39 *               
40 *                                              V
41 *                           +--(INCALL)--------+----(phPlaceCall)-------------------+
42 *                           |                                                       |
43 *                           |                                                       |
44 *                           v                                                       v           
45 *  +--(phRejectCall)--<-[INCOMING]<----<------- +                               [OUTGOING]--(DIALING/RINGING)-->-+
46 *  |                        v                   ^                                v   v  ^                        |
47 *  |                        |                   |                                |   |  |                        |
48 *  |                        +--(phRingingCall)--+                                |   |  |                        |
49 *  |                        |                                                    |   |  |                        |
50 *  |                        v                                                    |   |  |                        |
51 *  |                   (phAcceptCall)            +--------+                      |   |  +------------------------+
52 *  |                        |                 (DTMF)      |                      |   |
53 *  |                        |                    ^        |                  (CALLOK)|
54 *  |                        v                    |        v                      v   |
55 *  |                  [ACCEPTING]->--(ret==0)-->[ESTABLISHED]<--+---------+------+   +-------->+
56 *  |                        |                    v        v               ^                    v
57 *  |                        |                    |        |               |                    |
58 *  |                (CALLCLOSED/CALLERROR)       +   (CALLHELD/HOLDOK)    |    (CALLCLOSED/CALLERROR/CALLBUSY/NOANSWER/REDIRECTED)
59 *  |                        |                    |        |               |                    |
60 *  |                        |             (CALLCLOSED)    |               ^                    |
61 *  |                        v                    |        +->[ONHOLD]->(CALLRESUMED/RESUMEOK)  |
62 *  |                        |                    |             v                               |
63 *  |                        |                    |             |                               |
64 *  |                        |                    +<-----(CALLCLOSED)                           |
65 *  |                        |                    |                                             |
66 *  v                        |                    v                                             v
67 *  +------------------------+------->[CLOSED]<---+---------------------------------------------+
68 *
69 *
70 *   Blind transfer operation
71 *
72 *   Suppose we have 2 parties A and B  and a call 'cid'  established between them.
73 *   On the A's side the call is identified bu cidA  and on the B's side the call is identfied by cidB.
74 *   Suppose the user A  want to transfer the call to a 3rd party  P.
75 *   So A does :
76 *     phBlindTransferCall(cidA, "P");
77 *   this will cause following sequence of events:
78 *     1. B  will receive a CALLHELD event
79 *     2. B  will receive a XFERREQ  event for cidB containingg "P" as remoteUri and newcid field will
80 *           contain a callid for an automatically generated call to the new destination
81 *   A will receive a XFERPROGRESS event
82 *   P will receive a INCALL event
83 *   P will do:
84 *     phAcceptCall
85 *   B will receive CALLOK
86 *   A will receive XFEROK
87 *   A will get CALLCLOSED for cidA
88 *   B will get CALLCLOSED  for cidB
89 *
90 *  In case of failure transfer for whatever reason A will receive an
91 *   XFERFAIL event with status field containing SIP status code
92 *
93 *   the file ../miniua/minua.c contains the code demonstrating the usage of blind transfer
94 *
95 *
96 *  Assisted Transfer operation:
97 *
98 *   Suppose we have 2 parties A and B  and a call 'cid'  established between them.
99 *   On the A's side the call is identified bu cidA  and on the B's side the call is identfied by cidB.
100 *   Suppose the user A  want to transfer the call to a 3rd party  P.
101 *   So A does :
102 *     phHoldCall(cidA);
103 *   B will receive  CALLHELD event
104 *   A does:
105 *       newcid = phPlaceCall2("A", "P");
106 *   P Gets INCALL event with cidP0 and accepts it
107 *   A talks to B and then does
108 *     phHoldCall(newcid)
109 *   P gets CALLHELD event
110 *   A does
111 *     phTransferCall(cidA, newcid)
112 *   B  will receive a XFERREQ  event for cidB containing "P" as remoteUri and newcid field will
113 *      contain a callid for an automatically generated call to the new destination
114 *   A gets XFERPROGRESS events
115 *   P will get CALLREPLACED for cidP0 with newcid cidP1
116 *   A gets XFEROK event
117 *   A will get CALLCLOSED for cidA
118 *   B will get CALLCLOSED for cidB
119 *   P will get CALLCLOSED for cidP0 
120 *       
121 */
122
123#ifdef WIN32
124#if defined(BUILD_PHAPI_DLL)
125#define PHAPI_EXPORT __declspec(dllexport)
126#elif defined(PHAPI_DLL)
127#define PHAPI_EXPORT __declspec(dllimport)
128#endif
129#endif
130
131#ifndef PHAPI_EXPORT
132#define PHAPI_EXPORT
133#endif
134
135#ifndef PHAPI_VERSION_STRING
136#define PHAPI_VERSION_STRING "1.0.0"
137#endif
138
139#ifdef __cplusplus
140extern "C" {
141#endif
142
143enum phErrors {
144  PH_ERROR=1,    /* generic error */
145  PH_HOLDERR,     /* HOLD/RESUME error */
146  PH_BADID,      /* bad identity -  usually ther is no virtual line which correpond to 'from' or userid parameter */
147  PH_BADVLID,   /*  Bad virual line ID  */
148  PH_BADCID,     /* Bad callid */
149  PH_NOMEDIA,     /* No media stream avalable */
150  PH_NOTUNNEL,    /* Unable to create tunnel */
151  PH_NORESOURCES, /* No resources for operation */
152  PH_RPCERR,     /* RPC error */
153  PH_BADARG,      /* BAD argument */
154  PH_VLBUSY,       /* There is oparation pending on this VLINE */
155  PH_BADCFID,       /* bad conf call id */
156  PH_REDIRLOOP,    /* setFollomMe or blindTransfer creates a loop */
157  PH_NOTINIT       /* phapi isn't init */
158};
159
160#define PH_REFRESH_INTERVAL             30  /* 30 seconds */
161
162#define PH_SOCK_MODE_UDP 0
163#define PH_SOCK_MODE_HTTP_TUNNEL 1
164#define PH_STREAM_AUDIO (1 << 0)
165#define PH_STREAM_VIDEO_RX (1 << 1)
166#define PH_STREAM_VIDEO_TX (1 << 2)
167#define PH_STREAM_VIDEO (PH_STREAM_VIDEO_RX|PH_STREAM_VIDEO_TX)
168#define PH_OVERRIDE_AUDIO_ADDR (1 << 3)
169#define PH_OVERRIDE_VIDEO_ADDR (1 << 4)
170#define PH_NOMEDIA_STREAMS (1 << 5)
171#define PH_STREAM_DATA (1 << 6)
172#define PH_STREAM_MCSEND (1 << 7)
173#define PH_STREAM_MCRECV (1 << 8)
174
175
176/********************TELEPHONY*********************/
177
178/**
179 * Add virtual line
180 * The virtual line corresponds to identity/server/proxy triplet
181 *
182 * @param  displayname display name component of the SIP identity "displayname" <sip:username@host>
183 * @param  username    username   
184 * @param  host        the host component of SIP identity username@host corresponding to this virtual line
185 *                     if regTimeout != 0 'host' will designate the REGISTRAR server, in this case it may have form of host:port
186 *                     otherwise it should be set to IP address or hostname of the local machine
187 * @param  proxy       outgoing proxy URI  (all calls using this virtual line will be routed
188 *                     through this proxy)
189 * @param  regTimeout  registration timeout  (when 0 will NOT use registrations)
190 *                     to unergister one should do phDelVline (or phUnregister -- depreciated)
191 * @param  mobility    mobility value from enum ph_line_mobility
192 * @return             -1 in case of error vlid  in case of success
193 */
194PHAPI_EXPORT int phAddVline(const char* username, const char *host, const char*  proxy,  int regTimeout);
195PHAPI_EXPORT int phAddVline2(const char* displayname, const char* username, const char *host, const char*  proxy, int regTimeout);
196PHAPI_EXPORT int phAddVline3(const char* displayname, const char* username, const char *host, const char*  proxy, int regTimeout, int mobility);
197 
198/**
199 * Register virtual line
200 *  This will cause REGISTER request to be sent to server
201 *
202 * @param  vlid        Virual line id to register
203 * @return             0 in case of success
204 */
205PHAPI_EXPORT int phvlRegister(int vlid);
206
207/**
208* Set virtual line register timeout (must be call before phvlRegister)
209*
210* @param  vlid        Virual line id to register
211* @param  regTimeout  register timeout
212* @return             0 in case of success
213*/
214PHAPI_EXPORT int phvlSetRegisterTimeOut(int vlid, int regTimeout);
215       
216/**
217 * Delete virtual line
218 *  This will cause REGISTER request with timeout=0 to be sent to server if needed
219 *
220 * @param  vlid        Virual line id to remove
221 * @return             0 in case of success
222 */
223PHAPI_EXPORT int phDelVline(int vlid);
224
225
226/**
227 * @brief initialize the payload/codecs that are allowed to be handled by the SIP stack
228 */
229PHAPI_EXPORT void ph_payloads_init();
230       
231#define PH_STREAM_MAX_ATTRS 32
232
233struct ph_stream_params
234{
235  const char  *streamtype;    /*!<  "audio", "video", ... */
236  const char  *payloads;      /*!<  space separated list of accepted payloads, if NULL use default list */ 
237  const char  *streamaddr;    /*!<  ip address of the stream, if NULL use default address */
238  int   streamport;           /*!<  if != -1 stream port number else use default port */
239  const char  *attrs[PH_STREAM_MAX_ATTRS]; /*!<  NULL terminated list of RTP stream attributes    */
240};
241
242/**
243 * information about negotiated media streams
244 */ 
245struct ph_confirmed_media_info
246{
247  struct
248 {
249    int localport, remoteport;
250    char remoteip[32];
251  } audio;
252  struct
253  {
254    int localport, remoteport;
255    char remoteip[32];
256  } video;
257};
258
259/**
260 * Place an outgoing call using given virtual line
261 *
262 * @param vlid         virtual line id to use for the call
263 * @param uri          call destination address
264 * @param userData     application specific data
265 * @param rcid         call id of the original call (MUST BE ZERO)
266 * @param streams      which stream to activate
267 * @param adev         audio device for call
268 * @param audio_addr   audio stream address (NULL == default local address)
269 * @param video_addr   video stream address (NULL == default local address)
270 * @return             if positive the call id else error indication
271 */
272PHAPI_EXPORT int phLinePlaceCall(int vlid, const char *uri, void *userData, int rcid);
273PHAPI_EXPORT int phLinePlaceCall2(int vlid, const char *uri, void *userData, int rcid, int streams);
274PHAPI_EXPORT int phLinePlaceCall4(int vlid, const char *uri, void *userdata, int rcid, int streams, const char *adev, const char *audio_addr, const char *video_addr);
275PHAPI_EXPORT int phLinePlaceCall5(int vlid, const char *uri, void *userdata, int rcid, int streams, const char *adev, ...);
276
277/**
278 * Accept an incoming a call.
279 *
280 * @param cid          call id of call.
281 * @return             0 in case of success
282 */
283PHAPI_EXPORT int phAcceptCall2(int cid, void *userData);
284PHAPI_EXPORT int phAcceptCall3(int cid, void *userData, int streams);
285PHAPI_EXPORT int phAcceptCall4(int cid, void *userData, int streams, const char *audio_addr, const char *video_addr);
286
287/*
288 * Accept incoming call in multicast mode
289 * 
290 * @param cid  call id (it will be considered as master call)
291 * @param adev audio device (could be NULL to use defualt audio device)
292 * @param audioaddr  multicast ip addres for the audio stream
293 * @param port       port number for the audio stream
294 */
295PHAPI_EXPORT int phAcceptMcCall(int cid, const char *adev, const char *audioaddr, int port);
296
297
298/*
299 * Accept incoming call in multicast mode
300 * 
301 * @param cid  call id (it will be considered as slave id)
302 * @param mcid call id of the master call
303 * @param port       port number for the audio stream
304 */
305PHAPI_EXPORT int phAcceptMcCall2(int cid, int mcid);
306
307
308
309
310/*
311 * Place a call to a peer which will respiond with multicasted stream
312 * @param vlid         virtual line id to use for the call
313 * @param uri          call destination address
314 * @param userData     application specific data
315 * @param streams      which stream to activate
316 * @param adev         audio device for call
317 */
318PHAPI_EXPORT int phLinePlaceMcCall(int vlid, const char *uri, void *userdata, int streams, const char *adev);
319
320
321
322#define phAcceptCall(cid) phAcceptCall2(cid, 0)
323
324/**
325 * Reject the incoming call.
326 *
327 * @param cid          call id of call.
328 * @param reason       SIP reason code for the rejection
329 *                     suggested values: 486 - Busy Here, 488 - Not acceptable here
330 * @param uri          uri to stuff into Contact field in case of reason = 302
331 * @return             0 in case of success
332 */
333PHAPI_EXPORT int phRejectCall(int cid, int reason);
334PHAPI_EXPORT int phRejectCall2(int cid, const char *uri,int reason);
335
336
337/**
338 * Signal reining event to the remote side.
339 *
340 * @param cid          call id of call.
341 * @return             0 in case of success
342 */
343PHAPI_EXPORT int phRingingCall(int cid);
344
345/**
346 * Terminate a call.
347 *
348 * @param cid          call id of call.
349 * @return             0 in case of success
350 */
351PHAPI_EXPORT int phCloseCall(int cid);
352
353/**
354 * Perform an assisted  call transfer
355 *
356 * @param cid          call id of call.
357 * @param targetCid    call id of the destination call
358 * @return             txid  used in the subsequent transferProgress callback
359 */
360PHAPI_EXPORT int phTransferCall(int cid, int targetCid);
361
362PHAPI_EXPORT int phCallStartMedia(int cid, int streamFlags);
363PHAPI_EXPORT int phCallGetMediaInfo(int cid, struct ph_confirmed_media_info *mi);
364
365/**
366 * Get the SIP CallID for the given call
367 *
368 * @param cid  call id
369 * @param idbuf where to store the SIP  CallID string
370 * @param  bufsize size of te idbuf
371 */
372PHAPI_EXPORT int phCallGetSipCallID(int cid, char *idbuf,  int bufsize);
373
374
375
376/**
377 * Configure follow me address  for a virtual line.
378 * All incoming calls on this line  will be redirected to this address
379 *
380 * @param uri          destination of the forwarding
381 * @return             0 in case of success
382 */
383PHAPI_EXPORT int phLineSetFollowMe(int vlid, const char *uri);
384
385/**
386 * Set busy mode for a virtual line
387 * When activated all incoming calls will be answerd by busy signal
388 *
389 * @param busyFlag          when 0 busy mode is deactivated else activated
390 * @return             0 in case of success
391 */
392PHAPI_EXPORT int phLineSetBusy(int vlid, int busyFlag);
393
394
395
396/********************CHAT & PRESENCE*********************/
397
398/**
399 * Send a MESSAGE request
400 *
401 * @param vlid    virtual line id
402 * @param to      uri to put in the To: header
403 * @param target  request target-uri
404 * @param message  message to send
405 * @param mime  message mime type
406 * @param sipcid optional value for SIP CallID header
407 * @param cid  callid (used to send a message inside a dialog as per RFC 3428)
408 * @return  if positive msgid
409*/
410PHAPI_EXPORT int phLineSendMessage(int vlid, const char *uri,
411                                   const char *buff, const char *mime);
412PHAPI_EXPORT int phLineSendMessage2(int vlid, const char *target, const char *uri,
413                                   const char *buff, const char *mime, 
414                                    const char *sipcid);
415PHAPI_EXPORT int phCallSendMessage(int cid, const char *buff, const char *mime);
416
417
418enum ph_subs_type
419{ 
420  PH_SUBS_PRESENCE,    /*  regular presence events */ 
421  PH_SUBS_WINFO,        /* presence+watcher info */ 
422  PH_SUBS_PRESENCE_LIST, /* batched presence notifications */ 
423  PH_SUBS_CONFLIST,    /*  server based conference list */ 
424  PH_SUBS_SIPPROFILE,   /* server based contact list */ 
425  PH_SUBS_ADDRBOOK_QRY   /* query the addressbook for a contact list */ 
426};
427
428
429/**
430 * Subscribe to presence
431 *
432 * @param vlid virtual line id
433 * @param to subscribe to
434 * @param winfo value from enum ph_subs_type specifying subscription kind
435 * @param data value setted in X-Addressbook header option
436 * @param use_proxy if 0, don't use vline proxy for request uri
437 * @param expire expire time of the subscribe
438 * @return 0 if success else -1
439*/
440PHAPI_EXPORT int phLineSubscribe2(int vlid, const char *to, const int winfo, char *data, int use_proxy, int expire);
441
442/**
443 * Subscribe to presence
444 *
445 * @param vlid virtual line id
446 * @param to subscribe to
447 * @param winfo value from enum ph_subs_type specifying subscription kind
448 * @return 0 if success else -1
449*/
450PHAPI_EXPORT int phLineSubscribe(int vlid, const char *to, const int winfo);
451
452/**
453 * Unsubscribe to presence
454 *
455 * @param vlid virtual line id
456 * @param to subscribe to
457 * @param winfo value from enum ph_subs_type specifying subscription kind
458 * @return 0 if success else -1
459*/
460PHAPI_EXPORT int phLineUnsubscribe(int sid, int winfo);
461
462/**
463 * Publish my presence
464 *
465 * @param vlid virtual line id
466 * @param to subscribe to
467 * @param winfo message type to send
468 * @param evt value for Event  SIP header
469 * @param content_type content type ("application/pidf+xml", for example)
470 * @param content content
471 * @param expires  expiration timeout
472 * @return 0 if success else -1
473*/
474PHAPI_EXPORT int phLinePublish(int vlid, const char *to, int winfo, const char * content_type, const char * content);
475PHAPI_EXPORT int phLinePublish2(int vlid, const char *to, const char *evt, const char * content_type, const char * content,
476                                int expires);
477
478
479
480/********************AUDIO*********************/
481
482/**
483 * Send a DTMF to remote party
484 *
485 * @param cid          call id of call.
486 * @param dtmfChar     DTMF event to send
487 *                     ('0','1','2','3','4','5','6','7','8','9','0','#','A','B','C','D','!')
488 * @mode               bitmask specifying DTMF geneartion mode
489 *                     INBAND - the DTMF signal is mixed in the outgoing
490 *                     RTPPAYLOAD - the DTMF signal will be sent using telephone_event RTP payload
491 *                     SIP -  use application/dtmf content type for INFO method
492 *                     SIPRELAY - use application/dtmf-relay content type method
493 * @return             0 in case of success
494 */
495#define PH_DTMF_MODE_INBAND 1
496#define PH_DTMF_MODE_RTPPAYLOAD 2
497#define PH_DTMF_MODE_ALLRTP 3
498#define PH_DTMF_MODE_SIP 4       
499#define PH_DTMF_MODE_SIPRELAY 8 
500PHAPI_EXPORT int phSendDtmf(int cid, int dtmfChar, int mode);
501
502/**
503 * Play a sound file
504 *
505 * @param fileName     file to play (the file externsion will determine the codec to use
506 *                     .sw - 16bit signed PCM, .ul - uLaw, .al - aLaw, .gsm - GSM, (.wav on Windows)
507 * @param loop         when TRUE play the file in loop
508 * @return             0 in case of success
509 */
510PHAPI_EXPORT int phPlaySoundFile(const char *fileName , int loop);
511
512/**
513 * Stop playing a sound file
514 *
515 * @return             0 in case of success
516 */
517PHAPI_EXPORT int phStopSoundFile( void );
518
519/**
520 * Mix a sound file into the outgoing network audio stream
521 *
522 * @param cid          call id
523 * @param fileName     file to play - for the moment only
524 *                      RAW audio files containing 16Bit signed PCM sampled at 16KHZ are supported
525 * @return             0 in case of success
526 */
527PHAPI_EXPORT int phSendSoundFile(int cid, const char *fileName);
528
529/**
530 * Set speaker volume 
531 *
532 * @param      cid       call id (-1 for general volume, -2 for playing sounds)
533 * @param      volume    0 - 100
534 * @return             0 in case of success
535 */
536PHAPI_EXPORT int phSetSpeakerVolume(int cid,  int volume);
537
538/**
539 * Set recording level 
540 *
541 * @param      cid - call id (-1 for general recording level)
542 * @param      level    0 - 100
543 * @return             0 in case of success
544 */
545PHAPI_EXPORT int phSetRecLevel(int cid,  int level);
546
547/**
548 * Change Audio devices
549 * change the audio devices used by phApi. The change will take effect for
550 * the new calls only.
551 *
552 * @param  devstr    the same value as in phcfg.audio_dev
553 * @return           0 on success, or error code
554 *
555 */
556PHAPI_EXPORT int phChangeAudioDevices(const char *devstr);
557
558
559/**
560 * Change Video devices
561 * change the video devices used by phApi. The change will take effect for
562 * the new calls only.
563 *
564 * @param  devstr    the same value as in phcfg.audio_dev
565 * @return           0 on success, or error code
566 *
567 */
568PHAPI_EXPORT int phChangeVideoDevices(const char *devstr);
569
570/**
571 * Set the value for UserAgent header
572 *
573 * @param uastring              value ut use in UserAgent header
574 * @return      0 if succeeds, an error value otherwise
575 */
576PHAPI_EXPORT int  phSetUaString(const char *uastr);
577
578
579/********************CONFERENCING*********************/
580
581/*
582 *  conferencing APIs (not yet finished)
583 *
584 *  These Fuctions and callback events are avaialable to the confernce intiator application
585 *  The conference members are for the moment completely unaware of the fact that they are participating
586 *  in a conf call
587 *
588 */
589
590/**
591 * Create a conference
592 * Given a call id transform this call into a conference
593 * In case of success this API will provoke a deliverey of phCONFCREATED event, following
594 * by the phCONFJOINED event with memberCid = cid
595 *
596 * @param   cid  call id to tranform into the conference
597 * @return        if positive conference id  else error code
598 *
599 */
600PHAPI_EXPORT int phConfCreate(int cid);
601
602/**
603 * Invite a party to a conference
604 * This call is more or less equivalent to phLinePlaceCall followed by phConfAddMember
605 *
606 * @param   cid  call id to tranform into the conference
607 * @return        callid of the created call or error code
608 *
609 */
610PHAPI_EXPORT int phLineConfInvite(int vlid, int cfid, const char *uri);
611
612/**
613 * Add a given call to the given conference
614 * This will provoke phCONFJOINED event or phCONFJOINERROR event
615 *
616 * @param    cfid conference id
617 * @param    cid  call id to add ito the conference
618 * @return   0 or error code
619 *
620 */
621PHAPI_EXPORT int phConfAddMember(int cfid, int callid);
622
623/**
624 * Remove a call from the conference
625 * This will provoke phCONFLEFT event
626 * The removed call will be moved to LOCALHOLD state, if the application wish to terminate it
627 * it should call phCloseCall explicitly
628 *
629 * @param    cfid conference id
630 * @param    cid  call id to remove from the conference
631 * @return   0 or error code
632 *
633 */
634PHAPI_EXPORT int phConfRemoveMember(int cfid, int cid);
635
636/**
637 * Close the conference
638 * This will provoke phCONFCLOSED event
639 * all member calls will be moved to LOCALHOLD state
640 *
641 * @param    cfid conference id
642 * @return   0 or error code
643 *
644 */
645PHAPI_EXPORT int phConfClose(int cfid);
646
647
648/* Conference Test: simple implementation */
649
650/**
651 * Start conferencing btewwen to calls
652 * This will start mixing of audio streams coming from two correspodents
653 * @param    cid1 first call id to mix
654 * @param    cid2 second call id to mix
655 * @return   0 or error code
656 *
657 */ 
658PHAPI_EXPORT int phConf(int cid1, int cid2);
659
660/**
661 * Stop  conferencing between to calls
662 * This will stop mixing of audio streams coming from two correspodents
663 * @param    cid1 first call id to mix
664 * @param    cid2 second call id to mix
665 * @return   0 or error code
666 *
667 */ 
668PHAPI_EXPORT int phStopConf(int cid1, int cid2);
669
670
671
672
673
674/********************UTILS*********************/
675
676/**
677 * Set value of SIP "Contact:"  associated with given virtual line
678 * @param    vlid virtual line id
679 * @param    uri value of the "Contact:" header
680 * @param    translate if non-zero the uri will be translated by phApi to use local ip address, else the uri will be used as is.
681 * @return   0 or error code
682 *
683 */ 
684PHAPI_EXPORT  int phSetContact(int vlid, const char *uri);
685PHAPI_EXPORT  int phSetContact2(int vlid, const char *uri, int translate);
686
687
688/**
689 * Return the SIP address associated to the given virtual ine id
690 *
691 * @param vlid   --   virtual line id
692 * @param buf     --  the buffer that receive the SIP address
693 * @param bufsize -- the size of the buffer
694 * @return --  0 in case of success
695*/
696PHAPI_EXPORT int phLineGetSipAddress(int vlid, char buf[], int bufsize);
697
698/**
699 * Send an OPTIONS packet send OPTIONS packet using given destination over given
700 * virtual line
701 * 
702 * @param vlid  --  vlid
703 * @param to    --  uri to put in the To: header
704*/
705PHAPI_EXPORT int phLineSendOptions(int vlid, const char *to);
706
707/**
708 * Return the NAT router type and it's ip address
709 *
710 * @param   natType  string buffer to receive nat type string (possible "fcone,rcone,prcone,sym,open")
711 * @param   ntlen  sizeof natType buffer
712 * @param   fwip   firewall ip address buffer
713 * @param   sizeof of fwip buffer
714 * @return  error or success code
715 *
716 */
717PHAPI_EXPORT int phGetNatInfo(char *natType, int ntlen, char *fwip, int fwiplen);
718
719enum ph_line_mobility
720{
721
722  PH_LINE_MOBILITY_DEFAULT,
723  PH_LINE_MOBILITY_FIXED,
724  PH_LINE_MOBILITY_MOBILE
725};
726
727/**
728 * Set mobility flag on the vilrual line
729 *
730 * @param vlid virtual line id
731 * @param mobility value from enum ph_line_mobility
732 * @return mobility value or negative error code
733 *
734 */
735PHAPI_EXPORT int phLineGetMobility(int vlid);
736
737
738/**
739 * Return the codecs used for the given call
740 *
741 * @param   cid  call id in question
742 * @param   audioCodecBuf  buffer to return audio codec used (or NULL)
743 * @param   aBufLen  size of audioCodecBuf
744 * @param   videoCodecBuf  buffer to return video codec used (or NULL)
745 * @param   vBufLen  size of videoCodecBuf
746 * @return  0 or error code
747 *
748 */
749
750PHAPI_EXPORT int phCallGetCodecs(int cid, char *audioCodecBuf, int aBufLen, char *videoCodecBuf, int vBufLen);
751
752
753/**
754 * @brief Try to crash the application
755*/
756PHAPI_EXPORT int phCrash();
757
758
759/********************STRUCTS*********************/
760
761/**
762 * @enum phCallStateEvent
763 * @brief call progress events.
764 *
765 */ 
766enum  phCallStateEvent {
767        phDIALING, phRINGING, phNOANSWER, phCALLBUSY,
768        phCALLREDIRECTED, phCALLOK,     phCALLHELD, phINCALLREADY,
769        phCALLRESUMED, phHOLDOK, phRESUMEOK, phINCALL,
770        phCALLCLOSED, phCALLERROR, phDTMF, phXFERPROGRESS,
771        phXFEROK, phXFERFAIL, phXFERREQ, phCALLREPLACED,
772        phRINGandSTART, phRINGandSTOP, phCALLCLOSEDandSTOPRING
773};
774/**
775 * @struct phCallStateInfo
776 */
777struct phCallStateInfo {
778  enum phCallStateEvent event;
779  void *userData;              /*!< used to match placeCall with callbacks */ 
780  const char *localUri;        /*!< valid for all events execpt CALLCLOSED and DTMF */
781  int   newcid;                /*!< valid for CALLREPLACED and XFERREQ */
782  int   oldcid;                /*!< in case of CALL OK specifies the old CALL which was target of XFRERREQ */
783  int   vlid;                  /*!< virtual line id */
784  int   streams;               /*!< proposed (for phINCALL) and active (for other events) streams for the call */
785  char  *callinfo;             /*! pointer to Call-Info header value if available */ 
786  const char  *remoteUri;    /*!< valid for all events execpt CALLCLOSED, DTMF and CALLERROR */
787  int   errorCode;           /*!< valid for CALLERROR */
788  int   dtmfDigit;           /*!< valid for DTMF */
789  const char *remoteSdp;
790};
791typedef struct phCallStateInfo phCallStateInfo_t;
792
793
794/**
795 * @enum phMsgEvent
796 */
797enum phMsgEvent {
798    phMsgNew, phMsgOk, phMsgError
799};
800/**
801 * @struct phMsgStateInfo
802 */
803struct phMsgStateInfo {
804  enum phMsgEvent event;
805  int   status;
806  const char *from;
807  const char *to;
808  const char *ctype;
809  const char *subtype;
810  const char *content;
811  const char *rawctt;
812  int   cid;     /*!<  when non-zero this is message inside a dialog corresponding to call 'cid' */
813};
814typedef struct phMsgStateInfo  phMsgStateInfo_t;
815
816
817/**
818 * @enum phSubscriptionEvent
819 */
820enum phSubscriptionEvent {
821        phSubscriptionOk, phSubscriptionErrNotFound, phSubscriptionError
822};
823/**
824 * @struct phSubscriptionStateInfo
825 */
826struct phSubscriptionStateInfo  {
827        enum phSubscriptionEvent event;
828        int status;
829        char *from;
830        char *to;
831};
832typedef struct phSubscriptionStateInfo  phSubscriptionStateInfo_t;
833
834
835struct phPicture
836{
837        int width,height;
838        void *planes[4];
839        int strides[4];
840};
841typedef struct phPicture  phPicture_t;
842       
843/**
844 * @struct phVideoFrameReceivedEvent
845 */
846struct phVideoFrameReceivedEvent {
847        phPicture_t *frame_remote;
848        phPicture_t *frame_local;
849};
850typedef struct phVideoFrameReceivedEvent  phVideoFrameReceivedEvent_t;
851
852
853/**
854 * @enum phConfEvent
855 */
856enum phConfEvent {
857  phCONFCREATED,   /* conference is created */
858  phCONFJOINED,    /* memeber joined a the conferences */
859  phCONFLEFT,      /* member left a conference */
860  phCONFCLOSED,     /* coneference closed       */ 
861  phCONFJOINERROR,   /* error joining a member to a conference */
862  phCONFERROR       /* generic error */
863};
864/**
865 * @enum phConfStateInfo
866 */
867struct phConfStateInfo {
868  int  confEvent;
869  int  memberCid;  /* call id's for the calls participating in the conference */
870                   /* valid for CONFJOINED,CONFLEFT,CONFJOINERROR events      */
871  int  errorCode;
872};
873typedef struct phConfStateInfo phConfStateInfo_t;
874
875/**
876 * @struct phVideoConfig
877 */
878struct ph_videoconfig_s {
879#define PHAPI_VIDEO_LINE_50KBPS         0
880#define PHAPI_VIDEO_LINE_64KBPS         1
881#define PHAPI_VIDEO_LINE_128KBPS        2
882#define PHAPI_VIDEO_LINE_256KBPS        3
883#define PHAPI_VIDEO_LINE_512KBPS        4
884#define PHAPI_VIDEO_LINE_1024KBPS       5
885#define PHAPI_VIDEO_LINE_2048KBPS       6
886#define PHAPI_VIDEO_LINE_AUTOMATIC      5
887        int video_fps;
888        int video_camera_flip_frame;
889        int video_max_frame_size;
890        int video_webcam_capture_width; /** width x height for capture must be given. 320x240 is a good guess */
891        int video_webcam_capture_height;
892        int video_line_configuration;
893        int video_codec_max_bitrate;
894        int video_codec_min_bitrate;
895        char video_device[256];
896};
897
898/**
899 * @struct ph_videocodecconfig_s
900 * @brief temporary structure that holds codec config, to be set from GUI
901 */
902struct ph_videocodecconfig_s {
903        int minrate;
904        int maxrate;
905        int gopsize;
906        int qmin;
907        int qmax;
908        float b_offset;
909        float b_factor;
910        float i_offset;
911        float i_factor;
912        int compress;
913        int max_b_frame;
914        int f_quality;
915};
916
917typedef struct phTransferStateInfo phTransferStateInfo_t;
918typedef struct phRegStateInfo phRegStateInfo_t;
919typedef void (*phFrameDisplayCbk)(int cid, phVideoFrameReceivedEvent_t *ev);
920
921
922
923/********************MAIN*********************/
924
925/**
926 * @struct phCallbacks
927 * @brief  callbacks to the MMI
928 */
929struct phCallbacks {
930  void  (*callProgress)(int cid, const phCallStateInfo_t *info);       /*!< call progress callback routine */
931  void  (*transferProgress)(int cid, const phTransferStateInfo_t *info); /*!< transfer progress callback routine */
932  void  (*confProgress)(int cfid, const phConfStateInfo_t *info);        /*!< conference progress callback routine */
933  void  (*regProgress)(int regid, int regStatus);                       /*!< registration status (0 - OK, else SIP error code */
934  void  (*msgProgress)(int mid,  const phMsgStateInfo_t *info);
935  void  (*connectionLost)(const char* host, int port);                  /*!< TCP connection lost */
936  void  (*onNotify) (const char* event, const char* from, const char *ctt, const char* content);
937  void  (*subscriptionProgress)(int sid,  const phSubscriptionStateInfo_t *info);
938  phFrameDisplayCbk onFrameReady;
939  void  (*errorNotify) (enum phErrors error);
940};
941typedef struct phCallbacks phCallbacks_t;
942
943/**
944 * @var phcb
945 * @brief pointer to callback structure
946 *
947 */
948PHAPI_EXPORT extern phCallbacks_t *phcb;
949
950/**
951 * Initilize phApi
952 *
953 * @param cbk          pointer to callback descriptor
954 * @param server       string containing an ip address of the phApi server
955 *                     (ignored when in direct link mode)
956 * @param asyncmode    when != 0 a thread will be created to deliver
957 *                     callbacks asyncronously, othewise the client
958 *                     is supposed to call phPoll periodically to get
959 *                     phApi events delivered
960 *                     In DIRECT link mode this parameter is copied to the phcfg.asyncmode structure
961 *                     in client/server mode this parameter has client local meaning.
962 */
963PHAPI_EXPORT int phInit(phCallbacks_t *cbk, char *server, int asyncmode);
964
965/**
966 *  Terminate phApi
967 */
968PHAPI_EXPORT void phTerminate( void );
969
970/**
971 * Add authentication info
972 * the given info will be to send as authentication information
973 * when server request it.
974 *
975 * @param  username    username which will figure in the From: headers
976 *                     (usually the same as userid)
977 * @param  userid      userid field value
978 * @param  realm       authentication realm
979 * @param  passwd      password correspoinding to the userid
980 * @return             0 in case of success
981 */
982PHAPI_EXPORT int phAddAuthInfo(const char *username, const char *userid,
983              const char *passwd, const char *ha1,
984              const char *realm);
985
986/**
987 * Configure tunnel parameters:         This funtion should be call just before phInit, when the global variable phcfg
988 *                                                                      is properly set up.
989 *
990 * @param http_proxy                        IP address of http proxy in local network, set to 0 if there is no local proxy
991 * @param http_proxy_port                               Port of local http proxy
992 * @param httpt_server                          IP address of the HTTP TUNNEL SERVER that do the http to udp conversion
993 * @param httpt_server_port                     Port of the HTTP TUNNEL SERVER that do the http to udp conversion
994 * @param proxy_user                            User name used for authentication purpose
995 * @param proxy_passwd                          Password for proxy
996 * @param use_ssl                           if true request usage of SSL protocol
997 * @param autoconf                      If this is set to 1, this funtion will try to detect network configuration when it can't
998 *                                                                      setup a tunnel with given parameters.
999*/
1000PHAPI_EXPORT int phTunnelConfig(const char* http_proxy, const int http_proxy_port,
1001                                                                const char* httpt_server, const int httpt_server_port, 
1002                                                                const char *proxy_user, const char* proxy_passwd,
1003                                                                int use_ssl, int autotoconf);
1004
1005/**
1006  @var phIsInitialize
1007  @brief 1 : if phInit has been called and phTerminate has not been called
1008                 0 : Otherwise
1009*/
1010PHAPI_EXPORT extern int phIsInitialized;
1011
1012/**
1013 * Get the version of the phAPI module
1014 *
1015 * @return  encoded value corresponding to Version.Subversion.Release
1016 *
1017 */
1018PHAPI_EXPORT int phGetVersion(void);
1019
1020/**
1021 * Get the mecurial reivision of the phAPI module
1022 *
1023 * @return  the value of PHAPI_REVISION (hg tip --template="{rev}")or NULL if not set
1024 *
1025 */
1026PHAPI_EXPORT const char * phGetRevision(void);
1027
1028/**
1029 * poll for phApi events
1030 */
1031PHAPI_EXPORT int phPoll( void );
1032
1033
1034/**
1035 * Set debugging level (between 0 and 9)
1036 */
1037PHAPI_EXPORT void phSetDebugLevel(int);
1038PHAPI_EXPORT int  phGetDebugLevel();
1039
1040
1041/**
1042 * Define log file name
1043 */
1044PHAPI_EXPORT void phSetLogFileName(const char *name);
1045
1046
1047/**
1048 * Internal function. Do a register for all virtual lines
1049 */
1050PHAPI_EXPORT void phRefresh(void);
1051
1052/**
1053 * In the case of rpc mode, the phapi server port
1054 */
1055PHAPI_EXPORT extern unsigned short phServerPort;
1056
1057
1058#define phRegister(u, s) phRegister2(u, s, 3600)
1059#define phUnregister(u, s) phRegister2(u, s, 0)
1060#define PH_UNREG_MASK               0x8000            /* this mask is ored with regStatus to distingush REGISTER from UNREGISTER */
1061
1062#define phRelease(v) ((v) & 0xff)
1063#define phSubversion(v) ((v >> 8) & 0xff)
1064#define phVersion(v) ((v >> 16) & 0xff)
1065
1066
1067/********************VIDEO*********************/
1068
1069PHAPI_EXPORT int  phVideoControlChangeFps(int callid, int fps);
1070PHAPI_EXPORT int  phVideoControlChangeQuality(int callid, int quality);
1071PHAPI_EXPORT int  phVideoControlSetCameraFlip(int flip);
1072PHAPI_EXPORT int  phVideoControlSetWebcamCaptureResolution(int width, int height);
1073PHAPI_EXPORT int  phVideoControlSetBitrate(int callid, int maxrate, int minrate);
1074PHAPI_EXPORT void phVideoControlCodecSet(int, struct ph_videocodecconfig_s *);
1075PHAPI_EXPORT void phVideoControlCodecGet(int, struct ph_videocodecconfig_s *);
1076
1077
1078
1079/********************CONFIG*********************/
1080
1081/**
1082 * @struct phConfig
1083 * @brief ph API configuration info
1084 */
1085#define VAD_VALID_MASK 0x80000000
1086#define VAD_THRESHOLD_MASK 0x7fffffff
1087
1088// SPIKE_HDX:different configuration modes are available
1089enum PH_HDX_MODES {
1090  PH_HDX_MODE_MIC = 1,   /*!< Half Duplex mode where microphone signal has priority over speaker signal */
1091  PH_HDX_MODE_SPK = 2    /*!< Half Duplex mode where speaker signal has priority over microphone signal */
1092};
1093
1094
1095struct ph_config_s {
1096  char local_ip_addr[16];  /*!< ip address to use in case of muti-homed setup */
1097  char local_audio_rtp_port[16]; /*!< port number used for RTP data */
1098  char local_audio_rtcp_port[16]; /*!< port number used for RTCP data */
1099  char local_audio_rtp_port_max[16]; /*!< maximal port number used for RTP data */
1100  char local_audio_rtcp_port_max[16]; /*!< maximal port number used for RTCP data */
1101  char local_video_rtp_port[16]; /*!< port number used for video RTP data */ 
1102  char local_video_rtcp_port[16]; /*!< port number used for video RTCP data */ 
1103
1104  char sipport[16];              /*!< sip port number */
1105  int transport;                        /*!< sip transport */
1106  char nattype[16];         /*!< nat type (auto,none,fcone,rcone,prcone,sym)  */
1107  char audio_codecs[128];         /*!< comma separate list of codecs in order of priority */
1108  char video_codecs[128];         /*!< comma separate list of codecs in order of priority */
1109                            /* example: PCMU,PCMA,GSM,ILBC,SPEEX   */
1110
1111  int  asyncmode;           /*!< when true phApi creates a separate eXosip polling thread... in client/server mode MUST be TRUE */
1112  char audio_dev[64];       /*!< audio device identifier */
1113                            /* example: IN=2 OUT=1 ; 2 is input device and 1 is ouput device */
1114  int softboost;            /* to be removed */
1115  int nomedia;
1116  int noaec;                /* when non-zero - disable aec */
1117  unsigned int vad;         /* if bit31=1  DTX/VAD features activated and bits0-30 contains the power threshold */
1118  int cng;                  /* if 1,  CNG feature will be negotiated */
1119 
1120  // SPIKE_HDX: setting of hdxmode in phconfig
1121  int hdxmode;              /* if 0, half duplex mode is desactivated. otherwise check enum PH_HDX_MODES */ 
1122 
1123  int nat_refresh_udp_time;       /* timeout for udp sip address/port refresh (when 0 no-refresh) */
1124  int nat_refresh_tcp_time;       /* timeout for tcp sip address/port refresh (when 0 no-refresh) */
1125  int nat_refresh_time_adjust;/*  timeout adjustment (must be at most nat_refresh_time/2) nat_refresh_time */
1126  int ptime;                              /* default global ptime */
1127  int jitterdepth;           /* jitter buffer depth in miliseconds (if 0 default of 60 msecs is used) */
1128  int stream_timeout;            /* max allowed latency before timeout in second, 0 or -1 to disable */
1129  int nodefaultline;         /* temporary hack for implementing backward compatibility... Don't touch it */
1130  int autoredir;            /*!< when NONZERO the redirect requests will be automatically executed by phApi
1131                              the new CID will be deliverd in newcid field  in the CALLREDIRECTED event */
1132  char stunserver[128]; /*!< stun server address:port or name:port */
1133
1134#define PH_TUNNEL_SSL 4
1135#define PH_TUNNEL_AUTOCONF 2
1136#define PH_TUNNEL_USE  1
1137  int  use_tunnel; 
1138
1139  char httpt_server[128];
1140  int  httpt_server_port;
1141  char http_proxy[128];
1142  int  http_proxy_port;
1143  char http_proxy_user[128];
1144  char http_proxy_passwd[128];
1145#ifdef WIN32
1146  void* videoHandle;
1147#endif
1148
1149  struct ph_videoconfig_s video_config;
1150  char  plugin_path[256];  /*!< where to look for plugin modules */
1151  int qos;                  /* QoS bits to add to TOS to : 0x2 min cost, 0x4 max reliability, 0x8 max throughput, 0x10 min delay */
1152  unsigned int hdxlevel;    /* if bit31=1  HDX level is valid and bits0-30 contains the power threshold */
1153
1154};
1155
1156
1157typedef struct ph_config_s ph_config_t;
1158
1159/**
1160 * @brief retrieve pointer to phapi config structure
1161 */
1162
1163PHAPI_EXPORT ph_config_t *ph_get_config();
1164
1165
1166/* JT */
1167#ifdef QOS_DEBUG_ENABLE
1168PHAPI_EXPORT void phrtcp_QoS_enable_rtcp_report(int ToF);
1169PHAPI_EXPORT void phrtcp_report_set_cb(jt_rtcpCallbacks_t *cbk);
1170PHAPI_EXPORT int phrtcp_report_begin();
1171PHAPI_EXPORT int phrtcp_report_end();
1172#endif /* QOS_DEBUG_ENABLE */
1173
1174
1175/** Sound API **/
1176
1177struct ph_audio_card_desc_s
1178{
1179  char *id;
1180  char *name;
1181  unsigned int capabilities;
1182};
1183
1184typedef struct ph_audio_card_desc_s ph_audio_card_desc_t;
1185
1186struct ph_video_web_cam_desc_s
1187{
1188        char *id;
1189        char *name;
1190};
1191       
1192typedef struct ph_video_web_cam_desc_s ph_video_web_cam_desc_t;
1193       
1194/**
1195 * Return a list of available sound cards for capture
1196 * @param   device_tab  an array containing available ph_audio_card_desc_t
1197 * @return  number of device in the array or -1 on error
1198 */
1199
1200PHAPI_EXPORT int phAudioCaptureCardList(ph_audio_card_desc_t** device_tab);
1201
1202/**
1203 * Return a list of available sound cards for playback
1204 * @param   device_tab  an array containing available ph_audio_card_desc_t
1205 * @return  number of device in the array or -1 on error
1206 */
1207
1208PHAPI_EXPORT int phAudioPlaybackCardList(ph_audio_card_desc_t** device_tab);
1209
1210/**
1211 * Return a list of available webcam
1212 * @param   device_tab  an array containing available ph_video_cam_desc_t
1213 * @return  number of device in the array or -1 on error
1214 */
1215PHAPI_EXPORT int phVideoWebcamList(ph_video_web_cam_desc_t ** device_tab);
1216
1217/**
1218 * Apply a gain to the input signal
1219 * @param   cid   call associated with the audiostream
1220 * @param   gain  gain applied to the input signal
1221 * @return  0 if successfull, <0 otherwise.
1222 */
1223PHAPI_EXPORT int phAudioSoftRecvVolumeGain(int cid, float gain);
1224
1225/**
1226 * Apply a gain to the output signal
1227 * @param   cid   call associated with the audiostream
1228 * @param   gain  gain applied to the output signal
1229 * @return  0 if successfull, <0 otherwise.
1230 */
1231PHAPI_EXPORT int phAudioSoftSendVolumeGain(int cid, float gain);
1232
1233/**
1234 * Set playback mixer level value.
1235 * @param  cid    call associated with the audiostream
1236 * @param  percent  A volume level
1237 * @return  0 if successfull, <0 otherwise.
1238 */
1239PHAPI_EXPORT int phAudioRecvVolumeLevel(int cid, int percent);
1240
1241/**
1242 * Set capture mixer level value.
1243 * @param  cid    call associated with the audiostream
1244 * @param  percent  A volume level
1245 * @return  0 if successfull, <0 otherwise.
1246 */
1247PHAPI_EXPORT int phAudioSendVolumeLevel(int cid, int percent);
1248
1249/**
1250 * Mute playback mixer
1251 * @param  cid    call associated with the audiostream
1252 * @param  val    mute status 0: unmute, 1: mute
1253 * @return  0 if successfull, <0 otherwise.
1254 */
1255PHAPI_EXPORT int phAudioMutePlayback(int cid, int val);
1256
1257/**
1258 * Mute capture mixer
1259 * @param  cid    call associated with the audiostream
1260 * @param  val    mute status 0: unmute, 1: mute
1261 * @return  0 if successfull, <0 otherwise.
1262 */
1263PHAPI_EXPORT int phAudioMuteCapture(int cid, int val);
1264
1265
1266#ifdef __cplusplus
1267}
1268#endif
1269
1270/** @} */
1271#endif
Note: See TracBrowser for help on using the repository browser.