source: verona/phapi/phapi.h @ 173:b1f45e2521be

Last change on this file since 173:b1f45e2521be was 173:b1f45e2521be, checked in by laurent <laurent@…>, 2 years ago

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