3rdparty/iaxclient/lib/iaxclient.h

   1 /*
   2  * iaxclient: a cross-platform IAX softphone library
   3  *
   4  * Copyrights:
   5  * Copyright (C) 2003-2006, Horizon Wimba, Inc.
   6  * Copyright (C) 2007, Wimba, Inc.
   7  *
   8  * Contributors:
   9  * Steve Kann <stevek@stevek.com>
  10  * Frik Strecker <frik@gatherworks.com>
  11  * Mihai Balea <mihai AT hates DOT ms>
  12  * Peter Grayson <jpgrayson@gmail.com>
  13  * Bill Cholewka <bcholew@gmail.com>
  14  * Erik Bunce <kde@bunce.us>
  15  *
  16  * This program is free software, distributed under the terms of
  17  * the GNU Lesser (Library) General Public License.
  18  */
  19 #ifndef _iaxclient_h
  20 #define _iaxclient_h
  21
  22 #ifdef __cplusplus
  23 extern "C" {
  24 #endif
  25
  26 /*!
  27   \file iaxclient.h
  28   \brief The IAXClient API
  29
  30
  31
  32   \note This is the include file which declares all external API functions to
  33   IAXClient.  It should include all functions and declarations needed
  34   by IAXClient library users, but not include internal structures, or
  35   require the inclusion of library internals (or sub-libraries)
  36 */
  37
  38 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  39 #ifdef _MSC_VER
  40 typedef int socklen_t;
  41 #endif
  42 #if defined(WIN32)  ||  defined(_WIN32_WCE)
  43 #include "winsock2.h"
  44 #else
  45 #include <sys/socket.h>
  46 #endif
  47
  48 // FlightGear modification: for FreeBSD compat
  49 #if !defined(WIN32)
  50     #include <sys/time.h> // for struct timeval
  51 #endif
  52
  53 #ifdef BUILDING_DLL
  54 # if defined(WIN32) ||  defined(_WIN32_WCE)
  55 #  ifdef _MSC_VER
  56 #   define EXPORT __declspec(dllexport)
  57 #  else
  58 #   define EXPORT  __stdcall __declspec(dllexport)
  59 #  endif
  60 # else
  61 #  define EXPORT
  62 #endif
  63 #else
  64 # define EXPORT
  65 #endif
  66 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
  67
  68 #if defined(WIN32)  ||  defined(_WIN32_WCE)
  69 #if defined(_MSC_VER)
  70         typedef int (__stdcall *iaxc_sendto_t)(SOCKET, const void *, size_t, int,
  71                         const struct sockaddr *, socklen_t);
  72         typedef int (__stdcall *iaxc_recvfrom_t)(SOCKET, void *, size_t, int,
  73                         struct sockaddr *, socklen_t *);
  74 #else
  75         typedef int PASCAL (*iaxc_sendto_t)(SOCKET, const char *, int, int,
  76                         const struct sockaddr *, int);
  77         typedef int PASCAL (*iaxc_recvfrom_t)(SOCKET, char *, int, int,
  78                         struct sockaddr *, int *);
  79 #endif
  80 #else
  81         /*!
  82                 Defines the portotype for an application provided sendto implementation.
  83         */
  84         typedef int (*iaxc_sendto_t)(int, const void *, size_t, int,
  85                         const struct sockaddr *, socklen_t);
  86         /*!
  87                 Defines the portotype for an application provided recvfrom implementation.
  88         */
  89         typedef int (*iaxc_recvfrom_t)(int, void *, size_t, int,
  90                         struct sockaddr *, socklen_t *);
  91 #endif
  92
  93 /*!
  94         Mask containing all potentially valid audio formats
  95 */
  96 #define IAXC_AUDIO_FORMAT_MASK  ((1<<16)-1)
  97
  98 /*!
  99         Mask containing all potentially valid video formats
 100 */
 101 #define IAXC_VIDEO_FORMAT_MASK  (((1<<25)-1) & ~IAXC_AUDIO_FORMAT_MASK)
 102
 103 /* payload formats : WARNING: must match libiax values!!! */
 104 /* Data formats for capabilities and frames alike */
 105 #define IAXC_FORMAT_G723_1       (1 << 0)   /*!< G.723.1 compression */
 106 #define IAXC_FORMAT_GSM          (1 << 1)   /*!< GSM compression */
 107 #define IAXC_FORMAT_ULAW         (1 << 2)   /*!< Raw mu-law data (G.711) */
 108 #define IAXC_FORMAT_ALAW         (1 << 3)   /*!< Raw A-law data (G.711) */
 109 #define IAXC_FORMAT_G726         (1 << 4)   /*!< ADPCM, 32kbps  */
 110 #define IAXC_FORMAT_ADPCM        (1 << 5)   /*!< ADPCM IMA */
 111 #define IAXC_FORMAT_SLINEAR      (1 << 6)   /*!< Raw 16-bit Signed Linear (8000 Hz) PCM */
 112 #define IAXC_FORMAT_LPC10        (1 << 7)   /*!< LPC10, 180 samples/frame */
 113 #define IAXC_FORMAT_G729A        (1 << 8)   /*!< G.729a Audio */
 114 #define IAXC_FORMAT_SPEEX        (1 << 9)   /*!< Speex Audio */
 115 #define IAXC_FORMAT_ILBC         (1 << 10)  /*!< iLBC Audio */
 116
 117 #define IAXC_FORMAT_MAX_AUDIO    (1 << 15)  /*!< Maximum audio format value */
 118 #define IAXC_FORMAT_JPEG         (1 << 16)  /*!< JPEG Images */
 119 #define IAXC_FORMAT_PNG          (1 << 17)  /*!< PNG Images */
 120 #define IAXC_FORMAT_H261         (1 << 18)  /*!< H.261 Video */
 121 #define IAXC_FORMAT_H263         (1 << 19)  /*!< H.263 Video */
 122 #define IAXC_FORMAT_H263_PLUS    (1 << 20)  /*!< H.263+ Video */
 123 #define IAXC_FORMAT_H264         (1 << 21)  /*!< H264 Video */
 124 #define IAXC_FORMAT_MPEG4        (1 << 22)  /*!< MPEG4 Video */
 125 #define IAXC_FORMAT_THEORA       (1 << 24)  /*!< Theora Video */
 126 #define IAXC_FORMAT_MAX_VIDEO    (1 << 24)  /*!< Maximum Video format value*/
 127
 128 #define IAXC_EVENT_TEXT          1   /*!< Indicates a text event */
 129 #define IAXC_EVENT_LEVELS        2   /*!< Indicates a level event */
 130 #define IAXC_EVENT_STATE         3   /*!< Indicates a call state change event */
 131 #define IAXC_EVENT_NETSTAT       4   /*!< Indicates a network statistics update event */
 132 #define IAXC_EVENT_URL           5   /*!< Indicates a URL push via IAX(2) */
 133 #define IAXC_EVENT_VIDEO         6   /*!< Indicates a video event */
 134 #define IAXC_EVENT_REGISTRATION  8   /*!< Indicates a registration event */
 135 #define IAXC_EVENT_DTMF          9   /*!< Indicates a DTMF event */
 136 #define IAXC_EVENT_AUDIO         10  /*!< Indicates an audio event */
 137 #define IAXC_EVENT_VIDEOSTATS    11  /*!< Indicates a video statistics update event */
 138 #define IAXC_EVENT_VIDCAP_ERROR  12  /*!< Indicates a video capture error occurred */
 139 #define IAXC_EVENT_VIDCAP_DEVICE 13  /*!< Indicates a possible video capture device insertion/removal */
 140
 141 #define IAXC_CALL_STATE_FREE     0       /*!< Indicates a call slot is free */
 142 #define IAXC_CALL_STATE_ACTIVE   (1<<1)  /*!< Indicates a call is active */
 143 #define IAXC_CALL_STATE_OUTGOING (1<<2)  /*!< Indicates a call is outgoing */
 144 #define IAXC_CALL_STATE_RINGING  (1<<3)  /*!< Indicates a call is ringing */
 145 #define IAXC_CALL_STATE_COMPLETE (1<<4)  /*!< Indicates a completed call */
 146 #define IAXC_CALL_STATE_SELECTED (1<<5)  /*!< Indicates the call is selected */
 147 #define IAXC_CALL_STATE_BUSY     (1<<6)  /*!< Indicates a call is busy */
 148 #define IAXC_CALL_STATE_TRANSFER (1<<7)  /*!< Indicates the call transfer has been released */
 149
 150 /*! Indicates that text is for an IAXClient status change */
 151 #define IAXC_TEXT_TYPE_STATUS     1
 152 /*!  Indicates that text is an IAXClient warning message */
 153 #define IAXC_TEXT_TYPE_NOTICE     2
 154 /*!  Represents that text is for an IAXClient error message */
 155 #define IAXC_TEXT_TYPE_ERROR      3
 156 /*!
 157         Represents that text is for an IAXClient fatal error message.
 158
 159         The User Agent should probably display error message text, then die
 160 */
 161 #define IAXC_TEXT_TYPE_FATALERROR 4
 162 /*!  Represents a message sent from the server across the IAX stream*/
 163 #define IAXC_TEXT_TYPE_IAX        5
 164
 165 /* registration replys, corresponding to IAX_EVENTs*/
 166 #define IAXC_REGISTRATION_REPLY_ACK     18   /*!< Indicates the registration was accepted (See IAX_EVENT_REGACC)  */
 167 #define IAXC_REGISTRATION_REPLY_REJ     30   /*!< Indicates the registration was rejected (See IAX_EVENT_REGREJ)  */
 168 #define IAXC_REGISTRATION_REPLY_TIMEOUT 6    /*!< Indicates the registration timed out (See IAX_EVENT_TIMEOUT) */
 169
 170 #define IAXC_URL_URL              1  /*!< URL received */
 171 #define IAXC_URL_LDCOMPLETE       2  /*!< URL loading complete */
 172 #define IAXC_URL_LINKURL          3  /*!< URL link request */
 173 #define IAXC_URL_LINKREJECT       4  /*!< URL link reject */
 174 #define IAXC_URL_UNLINK           5  /*!< URL unlink */
 175
 176 /* The source of the video or audio data triggering the event. */
 177 #define IAXC_SOURCE_LOCAL  1 /*!<  Indicates that the event data source is local */
 178 #define IAXC_SOURCE_REMOTE 2 /*!<  Indicates that the event data source is remote */
 179
 180 /*!
 181         The maximum size of a string contained within an event
 182  */
 183 #define IAXC_EVENT_BUFSIZ 256
 184
 185 /*!
 186         A structure containing information about an audio level event.
 187 */
 188 struct iaxc_ev_levels {
 189         /*!
 190                 The input level in dB.
 191         */
 192         float input;
 193
 194         /*!
 195                 The output level in dB.
 196         */
 197         float output;
 198 };
 199
 200 /*!
 201         A structure containing information about a text event.
 202 */
 203 struct iaxc_ev_text {
 204         /*!
 205                 The type of text event.
 206
 207                 Valid values are from the IAXC_TEXT_TYPE_{} family of defines.
 208                 \see IAXC_TEXT_TYPE_STATUS, IAXC_TEXT_TYPE_NOTICE, IAXC_TEXT_TYPE_ERROR,
 209                 IAXC_TEXT_TYPE_FATALERROR, IAXC_TEXT_TYPE_IAX
 210         */
 211         int type;
 212
 213         /*!
 214                 The call the text is associated with or -1 if general text.
 215         */
 216         int callNo;
 217
 218         /*!
 219                 The UTF8 encoded text of the message.
 220         */
 221         char message[IAXC_EVENT_BUFSIZ];
 222 };
 223
 224 /*!
 225         A structure containing information about a call state change event.
 226 */
 227 struct iaxc_ev_call_state {
 228         /*!
 229                 The call number whose state this is
 230         */
 231         int callNo;
 232
 233         /*!
 234                 The call state represented using the IAXC_CALL_STATE_{} defines.
 235
 236                 \see IAXC_CALL_STATE_FREE, IAXC_CALL_STATE_ACTIVE, IAXC_CALL_STATE_OUTGOING,
 237                 IAXC_CALL_STATE_RINGING, IAXC_CALL_STATE_COMPLETE, IAXC_CALL_STATE_SELECTED,
 238                 IAXC_CALL_STATE_BUSY, IAXC_CALL_STATE_TRANSFER
 239         */
 240         int state;
 241
 242         /*!
 243                 The audio format of the call.
 244
 245                 \see IAXC_FORMAT_G723_1, IAXC_FORMAT_GSM, IAXC_FORMAT_ULAW, IAXC_FORMAT_ALAW,
 246                 IAXC_FORMAT_G726, IAXC_FORMAT_ADPCM, IAXC_FORMAT_SLINEAR, IAXC_FORMAT_LPC10,
 247                 IAXC_FORMAT_G729A, IAXC_FORMAT_SPEEX, IAXC_FORMAT_ILBC, IAXC_FORMAT_MAX_AUDIO
 248         */
 249         int format;
 250
 251         /*!
 252                 The audio format of the call.
 253
 254                 \see IAXC_FORMAT_JPEG, IAXC_FORMAT_PNG, IAXC_FORMAT_H261, IAXC_FORMAT_H263,
 255                 IAXC_FORMAT_H263_PLUS, IAXC_FORMAT_H264, IAXC_FORMAT_MPEG4,
 256                 IAXC_FORMAT_THEORA, IAXC_FORMAT_MAX_VIDEO
 257         */
 258         int vformat;
 259
 260         /*!
 261                 The remote number.
 262         */
 263         char remote[IAXC_EVENT_BUFSIZ];
 264
 265         /*!
 266                 The remote name.
 267         */
 268         char remote_name[IAXC_EVENT_BUFSIZ];
 269
 270         /*!
 271                 The local number.
 272         */
 273         char local[IAXC_EVENT_BUFSIZ];
 274
 275         /*!
 276                 The local calling context.
 277         */
 278         char local_context[IAXC_EVENT_BUFSIZ];
 279 };
 280
 281 /*!
 282         A structure containing information about a set of network statistics.
 283 */
 284 struct iaxc_netstat {
 285         /*!
 286                 The amount of observed jitter.
 287         */
 288         int jitter;
 289
 290         /*!
 291                 The lost frame percentage.
 292         */
 293         int losspct;
 294
 295         /*!
 296                 The number of missing frames.
 297         */
 298         int losscnt;
 299
 300         /*!
 301                 The number of frames received.
 302         */
 303         int packets;
 304
 305         /*!
 306                 The observed delay.
 307         */
 308         int delay;
 309
 310         /*!
 311                 The number of frames dropped.
 312         */
 313         int dropped;
 314
 315         /*!
 316                 The number of frames received out of order.
 317         */
 318         int ooo;
 319 };
 320
 321 /*!
 322         A structure containing information about a network statistics event.
 323 */
 324 struct iaxc_ev_netstats {
 325         /*!
 326                 The call whose statistics these are.
 327         */
 328         int callNo;
 329
 330         /*!
 331                 The Round Trip Time
 332         */
 333         int rtt;
 334
 335         /*!
 336                 The locally observed network statistics.
 337         */
 338         struct iaxc_netstat local;
 339
 340         /*!
 341                 The remotely (peer) observed network statistics.
 342         */
 343         struct iaxc_netstat remote;
 344 };
 345
 346 /*!
 347         A structure containing video statistics data.
 348 */
 349 struct iaxc_video_stats
 350 {
 351         unsigned long received_slices;  /*!< Number of received slices. */
 352         unsigned long acc_recv_size;    /*!< Accumulated size of inbound slices. */
 353         unsigned long sent_slices;      /*!< Number of sent slices. */
 354         unsigned long acc_sent_size;    /*!< Accumulated size of outbound slices. */
 355
 356         unsigned long dropped_frames;   /*!< Number of frames dropped by the codec (incomplete frames). */
 357         unsigned long inbound_frames;   /*!< Number of frames decoded by the codec (complete frames). */
 358         unsigned long outbound_frames;  /*!< Number of frames sent to the encoder. */
 359
 360         float         avg_inbound_fps;  /*!< Average fps of inbound complete frames. */
 361         unsigned long avg_inbound_bps;  /*!< Average inbound bitrate. */
 362         float         avg_outbound_fps; /*!< Average fps of outbound frames. */
 363         unsigned long avg_outbound_bps; /*!< Average outbound bitrate. */
 364
 365         struct timeval start_time;      /*!< Timestamp of the moment we started measuring. */
 366 };
 367
 368 /*!
 369         A structure containing information about a video statistics event.
 370 */
 371 struct iaxc_ev_video_stats {
 372         /*!
 373                 The call whose statistics these are.
 374         */
 375         int callNo;
 376
 377         /*!
 378                 The video statistics for the call.
 379         */
 380         struct iaxc_video_stats stats;
 381 };
 382
 383 /*!
 384         A structure containing information about an URL event.
 385 */
 386 struct iaxc_ev_url {
 387         /*!
 388                 The call this is for.
 389         */
 390         int callNo;
 391
 392         /*!
 393                 The type of URL received. See the IAXC_URL_{} defines.
 394
 395                 \see IAXC_URL_URL, IAXC_URL_LINKURL, IAXC_URL_LDCOMPLETE, IAXC_URL_UNLINK,
 396                 IAXC_URL_LINKREJECT
 397         */
 398         int type;
 399
 400         /*!
 401                 The received URL.
 402         */
 403         char url[IAXC_EVENT_BUFSIZ];
 404 };
 405
 406 /*!
 407         A structure containing data for a video event.
 408 */
 409 struct iaxc_ev_video {
 410         /*!
 411                 The call this video data is for.
 412
 413                 Will be -1 for local video.
 414         */
 415         int callNo;
 416
 417         /*!
 418                 Timestamp of the video
 419         */
 420         unsigned int ts;
 421
 422         /*!
 423                 The format of the video data.
 424
 425         \see IAXC_FORMAT_JPEG, IAXC_FORMAT_PNG, IAXC_FORMAT_H261, IAXC_FORMAT_H263,
 426         IAXC_FORMAT_H263_PLUS, IAXC_FORMAT_H264, IAXC_FORMAT_MPEG4,
 427         IAXC_FORMAT_THEORA, IAXC_FORMAT_MAX_VIDEO
 428         */
 429         int format;
 430
 431         /*!
 432                 The width of the video.
 433         */
 434         int width;
 435
 436         /*!
 437                 The height of the video.
 438         */
 439         int height;
 440
 441         /*!
 442                 Is the data encoded.
 443
 444                 1 for encoded data, 0 for raw.
 445         */
 446         int encoded;
 447
 448         /*!
 449                 The source of the data.
 450
 451                 \see IAXC_SOURCE_LOCAL, IAXC_SOURCE_REMOTE
 452         */
 453         int source;
 454
 455         /*!
 456                 The size of the video data in bytes.
 457         */
 458         int size;
 459
 460         /*!
 461                 The buffer containing the video data.
 462         */
 463         char *data;
 464 };
 465
 466 /*!
 467         A structure containing data for an audio event.
 468 */
 469 struct iaxc_ev_audio
 470 {
 471         /*!
 472                 The call this audio data is for.
 473         */
 474         int callNo;
 475
 476         /*!
 477                 Timestamp of the video
 478         */
 479         unsigned int ts;
 480
 481         /*!
 482                 The format of the data.
 483
 484         \see IAXC_FORMAT_G723_1, IAXC_FORMAT_GSM, IAXC_FORMAT_ULAW, IAXC_FORMAT_ALAW,
 485         IAXC_FORMAT_G726, IAXC_FORMAT_ADPCM, IAXC_FORMAT_SLINEAR, IAXC_FORMAT_LPC10,
 486         IAXC_FORMAT_G729A, IAXC_FORMAT_SPEEX, IAXC_FORMAT_ILBC, IAXC_FORMAT_MAX_AUDIO
 487         */
 488         int format;
 489
 490         /*!
 491                 Is the data encoded.
 492
 493                 1 for encoded data, 0 for raw.
 494         */
 495         int encoded;
 496
 497         /*!
 498                 The source of the data.
 499
 500                 \see IAXC_SOURCE_LOCAL, IAXC_SOURCE_REMOTE
 501         */
 502         int source;
 503
 504         /*!
 505                 The size of the audio data in bytes.
 506         */
 507         int size;
 508
 509         /*!
 510                 The buffer containing the audio data.
 511         */
 512         unsigned char *data;
 513 };
 514
 515 /*!
 516         A structure containing information about a registration event
 517 */
 518 struct iaxc_ev_registration {
 519         /*!
 520                 Indicates the registration id this event corresponds to.
 521
 522                 \see iaxc_register
 523         */
 524         int id;
 525
 526         /*!
 527                 The registration reply.
 528
 529                 The values are from the IAXC_REGISTRATION_REPLY_{} family of macros.
 530                 \see IAX_EVENT_REGACC, IAX_EVENT_REGREJ, IAX_EVENT_TIMEOUT
 531         */
 532         int reply;
 533
 534         /*!
 535                 The number of 'voicemail' messages.
 536         */
 537         int msgcount;
 538 };
 539
 540 /*!
 541         A structure containing information about a DTMF event
 542  */
 543 struct iaxc_ev_dtmf {
 544         /*!
 545                 The call this DTMF event is for.
 546          */
 547         int  callNo;
 548
 549         /*!
 550                 The digit represented by this DTMF tone
 551          */
 552         char digit;
 553 };
 554
 555 /*!
 556         A structure describing a single IAXClient event.
 557 */
 558 typedef struct iaxc_event_struct {
 559         /*!
 560                 Points to the next entry in the event queue
 561                 \internal
 562         */
 563         struct iaxc_event_struct *next;
 564
 565         /*!
 566                 The type uses one of the IAXC_EVENT_{} macros to describe which type of
 567                 event is being presented
 568         */
 569         int type;
 570
 571         /*!
 572                 Contains the data specific to the type of event.
 573         */
 574         union {
 575                 /*! Contains level data if type = IAXC_EVENT_LEVELS */
 576                 struct iaxc_ev_levels           levels;
 577                 /*! Contains text data if type = IAXC_EVENT_TEXT */
 578                 struct iaxc_ev_text             text;
 579                 /*! Contains call state data if type = IAXC_EVENT_STATE */
 580                 struct iaxc_ev_call_state       call;
 581                 /*! Contains network statistics if type = IAXC_EVENT_NETSTAT */
 582                 struct iaxc_ev_netstats         netstats;
 583                 /*! Contains video statistics if type = IAXC_EVENT_VIDEOSTATS */
 584                 struct iaxc_ev_video_stats      videostats;
 585                 /*! Contains url data if type = IAXC_EVENT_URL */
 586                 struct iaxc_ev_url              url;
 587                 /*! Contains video data if type = IAXC_EVENT_VIDEO */
 588                 struct iaxc_ev_video            video;
 589                 /*! Contains audio data if type = IAXC_EVENT_AUDIO */
 590                 struct iaxc_ev_audio            audio;
 591                 /*! Contains registration data if type = IAXC_EVENT_REGISTRATION */
 592                 struct iaxc_ev_registration     reg;
 593                 /*! Contains DTMF data if type = IAXC_EVENT_DTMF */
 594                 struct iaxc_ev_dtmf             dtmf;
 595         } ev;
 596 } iaxc_event;
 597
 598 /*!
 599         Defines the prototype for event callback handlers
 600         \param e The event structure being passed to the callback
 601
 602         \return The result of processing the event; > 0 if successfully handled the event, 0 if not handled, < 0 to indicate an error occurred processing the event.
 603 */
 604 typedef int (*iaxc_event_callback_t)(iaxc_event e);
 605
 606 /*!
 607         Sets the callback to call with IAXClient events
 608         \param func The callback function to call with events
 609 */
 610 EXPORT void iaxc_set_event_callback(iaxc_event_callback_t func);
 611
 612 /*!
 613         Sets iaxclient to post a pointer to a copy of event using o/s specific Post method
 614         \param handle
 615         \param id
 616 */
 617 EXPORT int iaxc_set_event_callpost(void *handle, int id);
 618
 619 /*!
 620         frees event delivered via o/s specific Post method
 621         \param e The event to free
 622 */
 623 EXPORT void iaxc_free_event(iaxc_event *e);
 624
 625
 626 /* Event Accessors */
 627 /*!
 628         Returns the levels data associated with event \a e.
 629         \param e The event to retrieve the levels from.
 630 */
 631 EXPORT struct iaxc_ev_levels *iaxc_get_event_levels(iaxc_event *e);
 632
 633 /*!
 634         Returns the text data associated with event \a e.
 635         \param e The event to retrieve text from.
 636 */
 637 EXPORT struct iaxc_ev_text *iaxc_get_event_text(iaxc_event *e);
 638
 639 /*!
 640         Returns the event state data associated with event \a e.
 641         \param e The event to retrieve call state from.
 642 */
 643 EXPORT struct iaxc_ev_call_state *iaxc_get_event_state(iaxc_event *e);
 644
 645 /*!
 646         Set Preferred UDP Port:
 647         \param sourceUdpPort The source UDP port to prefer
 648         0 Use the default port (4569), <0 Uses a dynamically assigned port, and
 649         >0 tries to bind to the specified port
 650
 651         \note must be called before iaxc_initialize()
 652 */
 653 EXPORT void iaxc_set_preferred_source_udp_port(int sourceUdpPort);
 654
 655 /*!
 656         Returns the UDP port that has been bound to.
 657
 658         \return The UDP port bound to; -1 if no port or
 659 */
 660 EXPORT int iaxc_get_bind_port();
 661
 662 /*!
 663         Initializes the IAXClient library
 664         \param num_calls The maximum number of simultaneous calls to handle.
 665
 666         This initializes the IAXClient
 667 */
 668 EXPORT int iaxc_initialize(int num_calls);
 669
 670 /*!
 671         Shutsdown the IAXClient library.
 672
 673         This should be called by applications utilizing iaxclient before they exit.
 674         It dumps all calls, and releases any audio/video drivers being used.
 675
 676         \note It is unsafe to call most IAXClient API's after calling this!
 677 */
 678 EXPORT void iaxc_shutdown();
 679
 680 /*!
 681         Sets the formats to be used
 682         \param preferred The single preferred audio format
 683         \param allowed A mask containing all audio formats to allow
 684
 685         \see IAXC_FORMAT_G723_1, IAXC_FORMAT_GSM, IAXC_FORMAT_ULAW, IAXC_FORMAT_ALAW,
 686         IAXC_FORMAT_G726, IAXC_FORMAT_ADPCM, IAXC_FORMAT_SLINEAR, IAXC_FORMAT_LPC10,
 687         IAXC_FORMAT_G729A, IAXC_FORMAT_SPEEX, IAXC_FORMAT_ILBC, IAXC_FORMAT_MAX_AUDIO
 688 */
 689 EXPORT void iaxc_set_formats(int preferred, int allowed);
 690
 691 /*!
 692         Sets the minimum outgoing frame size.
 693         \param samples The minimum number of samples to include in an outgoing frame.
 694 */
 695 EXPORT void iaxc_set_min_outgoing_framesize(int samples);
 696
 697 /*!
 698         Sets the caller id \a name and \a number.
 699         \param name The caller id name.
 700         \param number The caller id number.
 701 */
 702 EXPORT void iaxc_set_callerid(const char * name, const char * number);
 703
 704 /*!
 705         Starts all the internal processing thread(s).
 706
 707         \note Should be called after iaxc_initialize, but before any call processing
 708         related functions.
 709 */
 710 EXPORT int iaxc_start_processing_thread();
 711
 712 /*!
 713         Stops all the internal processing thread(s).
 714
 715         \note Should be called before iaxc_shutdown.
 716 */
 717 EXPORT int iaxc_stop_processing_thread();
 718
 719 /*!
 720         Initiates a call to an end point
 721         \param num The entity to call in the format of [user[:password]]@@peer[:portno][/exten[@@context]]
 722
 723         \return The call number upon sucess; -1 otherwise.
 724
 725         \note This is the same as calling iaxc_call_ex(num, NULL, NULL, 1).
 726 */
 727 EXPORT int iaxc_call(const char * num);
 728
 729 /*!
 730         Initiates a call to an end point
 731         \param num The entity to call in the format of [user[:password]]@@peer[:portno][/exten[@@context]]
 732         \param callerid_name The local caller id name to use
 733         \param callerid_number The local caller id number to use
 734         \param video 0 indicates no-video. Any non-zero value indicates video is requested
 735
 736         \return The call number upon sucess; -1 otherwise.
 737 */
 738 EXPORT int iaxc_call_ex(const char* num, const char* callerid_name, const char* callerid_number, int video);
 739
 740 /*!
 741         Unregisters IAXClient from a server
 742         \param id The registration number returned by iaxc_register.
 743 */
 744 EXPORT int iaxc_unregister( int id );
 745
 746 /*!
 747         Registers the IAXClient instance with an IAX server
 748         \param user The username to register as
 749         \param pass The password to register with
 750         \param host The address of the host/peer to register with
 751
 752         \return The registration id number upon success; -1 otherwise.
 753 */
 754 EXPORT int iaxc_register(const char * user, const char * pass, const char * host);
 755
 756 /*!
 757         Registers the IAXClient instance with an IAX server
 758         \param user The username to register as
 759         \param pass The password to register with
 760         \param host The address of the host/peer to register with
 761         \param refresh The registration refresh period
 762
 763         \return The registration id number upon success; -1 otherwise.
 764 */
 765 EXPORT int iaxc_register_ex(const char * user, const char * pass, const char * host, int refresh);
 766
 767 /*!
 768         Respond to incoming call \a callNo as busy.
 769 */
 770 EXPORT void iaxc_send_busy_on_incoming_call(int callNo);
 771
 772 /*!
 773         Answers the incoming call \a callNo.
 774         \param callNo The number of the call to answer.
 775 */
 776 EXPORT void iaxc_answer_call(int callNo);
 777
 778 /*!
 779         Initiate a blind call transfer of \a callNo to \a number.
 780         \param callNo The active call to transfer.
 781         \param number The number to transfer the call to. See draft-guy-iax-03 section 8.4.1 for further details.
 782 */
 783 EXPORT void iaxc_blind_transfer_call(int callNo, const char * number);
 784
 785 /*!
 786         Setup a transfer of \a sourceCallNo to \a targetCallNo.
 787         \param sourceCallNo The number of the active call session to transfer.
 788         \param targetCallNo The active call session to be transferred to.
 789
 790         This is used in performing as the final step in an attended call transfer.
 791 */
 792 EXPORT void iaxc_setup_call_transfer(int sourceCallNo, int targetCallNo);
 793
 794 /*!
 795         Hangs up and frees all non-free calls.
 796 */
 797 EXPORT void iaxc_dump_all_calls(void);
 798
 799 /*!
 800         Hangs up and frees call \a callNo
 801         \param callNo The call number to reject.
 802 */
 803 EXPORT void iaxc_dump_call_number( int callNo );
 804
 805 /*!
 806         Hangs up and frees the currently selected call.
 807 */
 808 EXPORT void iaxc_dump_call(void);
 809
 810 /*!
 811         Rejects the currently selected call.
 812
 813         \note This is pretty much a useless API, since the act of selecting a call
 814         will answer it.
 815 */
 816 EXPORT void iaxc_reject_call(void);
 817
 818 /*!
 819         Rejects the incoming call \a callNo.
 820         \param callNo The call number to reject.
 821 */
 822 EXPORT void iaxc_reject_call_number(int callNo);
 823
 824 /*!
 825         Sends a DTMF digit to the currently selected call.
 826         \param digit The DTMF digit to send (0-9, A-D, *, #).
 827 */
 828 EXPORT void iaxc_send_dtmf(char digit);
 829
 830 /*!
 831         Sends text to the currently selected call.
 832 */
 833 EXPORT void iaxc_send_text(const char * text);
 834
 835 /*!
 836         Sends \a text to call \a callNo
 837 */
 838 EXPORT void iaxc_send_text_call(int callNo, const char * text);
 839
 840 /*!
 841         Sends a URL across the currently selected call
 842         \param url The URL to send across.
 843         \param link If non-zero the URL is a link
 844 */
 845 EXPORT void iaxc_send_url(const char *url, int link); /* link == 1 ? AST_HTML_LINKURL : AST_HTML_URL */
 846
 847 /*!
 848         Suspends thread execution for an interval measured in milliseconds
 849         \param ms The number of milliseconds to sleep
 850 */
 851 EXPORT void iaxc_millisleep(long ms);
 852
 853 /*!
 854         Sets the silence threshold to \a thr.
 855         \param thr The threshold value in dB. A value of 0.0f effectively mutes audio input.
 856 */
 857 EXPORT void iaxc_set_silence_threshold(float thr);
 858
 859 /*!
 860         Sets the audio output to \a mode.
 861         \param mode The audio mode 0 indicates remote audio should be played; non-zero prevents remote audio from being played.
 862 */
 863 EXPORT void iaxc_set_audio_output(int mode);
 864
 865 /*!
 866         Sets \a callNo as the currently selected call
 867         \param callNo The call to select or < 0 to indicate no selected call.
 868
 869         \note Will answer an incoming ringing call as a side effect. Personally I
 870         believe this behavior is undesirable and feel it renders iaxc_reject_call
 871         pretty much useless.
 872 */
 873 EXPORT int iaxc_select_call(int callNo);
 874
 875 /*!
 876         Returns the first free call number.
 877 */
 878 EXPORT int iaxc_first_free_call();
 879
 880 /*!
 881         Returns the number of the currently selected call.
 882 */
 883 EXPORT int iaxc_selected_call();
 884
 885 /*!
 886         Causes the audio channel for \a callNo to QUELCH (be squelched).
 887         \param callNo The number of the active, accepted call to quelch.
 888         \param MOH If non-zero Music On Hold should be played on the QUELCH'd call.
 889 */
 890 EXPORT int iaxc_quelch(int callNo, int MOH);
 891
 892 /*!
 893         Causes the audio channel for \a callNo to be UNQUELCH (unsquelched).
 894 */
 895 EXPORT int iaxc_unquelch(int callNo);
 896
 897 /*!
 898         Returns the current mic boost setting.
 899
 900         \return 0 if mic boost is disabled; otherwise non-zero.
 901 */
 902 EXPORT int iaxc_mic_boost_get( void ) ;
 903
 904 /*!
 905         Sets the mic boost setting.
 906         \param enable If non-zero enable the mic boost; otherwise disable.
 907 */
 908 EXPORT int iaxc_mic_boost_set( int enable ) ;
 909
 910 /*!
 911         Returns a copy of IAXClient library version
 912         \param ver A buffer to store the version string in. It MUST be at least
 913         IAXC_EVENT_BUFSIZ bytes in size.
 914
 915         \return the version string (as stored in \a ver).
 916 */
 917 EXPORT char* iaxc_version(char *ver);
 918
 919 /*!
 920         Fine tune jitterbuffer control
 921         \param value
 922 */
 923 EXPORT void iaxc_set_jb_target_extra( long value );
 924
 925 /*!
 926         Application-defined networking; give substitute sendto and recvfrom
 927         functions.
 928         \param st The send function to use.
 929         \param rf The receive function to use.
 930
 931         \note Must be called before iaxc_initialize!
 932 */
 933 EXPORT void iaxc_set_networking(iaxc_sendto_t st, iaxc_recvfrom_t rf) ;
 934
 935 /*!
 936         wrapper for libiax2 get_netstats
 937         \param call
 938         \param rtt
 939         \param local
 940         \param remote
 941 */
 942 EXPORT int iaxc_get_netstats(int call, int *rtt, struct iaxc_netstat *local, struct iaxc_netstat *remote);
 943
 944 /*!
 945         A structure containing information about a video capture device.
 946 */
 947 struct iaxc_video_device {
 948         /*!
 949                 The "human readable" name of the device
 950         */
 951         const char *name;
 952
 953         /*!
 954                 unique id of the device
 955         */
 956         const char *id_string;
 957
 958         /*!
 959                 iaxclient id of the device
 960         */
 961         int id;
 962 };
 963
 964 #define IAXC_AD_INPUT           (1<<0) /*!< Device is usable for input*/
 965 #define IAXC_AD_OUTPUT          (1<<1) /*!< Device is usable for output */
 966 #define IAXC_AD_RING            (1<<2) /*!< Device is usable for ring */
 967 #define IAXC_AD_INPUT_DEFAULT   (1<<3) /*!< Indicates the default input device */
 968 #define IAXC_AD_OUTPUT_DEFAULT  (1<<4) /*!< Indicates the default output device */
 969 #define IAXC_AD_RING_DEFAULT    (1<<5) /*!< Indicates the default ring device */
 970
 971 /*!
 972         A structure containing information about an audio device.
 973 */
 974 struct iaxc_audio_device {
 975         /*!
 976                 The "human readable" name of the device
 977         */
 978         const char * name;
 979
 980         /*!
 981                 Capability flags, defined using the IAXC_AD_{} macros.
 982         */
 983         long capabilities;
 984
 985         /*!
 986                 The device driver specific ID.
 987         */
 988         int devID;
 989 };
 990
 991 /*! Get audio device information:
 992          \param devs Returns an array of iaxc_audio_device structures.
 993                 The array will will be valid as long as iaxc is initialized.
 994          \param nDevs Returns the number of devices in the devs array
 995          \param input Returns the currently selected input device
 996          \param output Returns the currently selected output device
 997          \param ring Returns the currently selected ring device
 998  */
 999 EXPORT int iaxc_audio_devices_get(struct iaxc_audio_device **devs, int *nDevs, int *input, int *output, int *ring);
1000
1001 /*!
1002         Sets the current audio devices
1003         \param input The device to use for audio input
1004         \param output The device to use for audio output
1005         \param ring The device to use to present ring sounds
1006  */
1007 EXPORT int iaxc_audio_devices_set(int input, int output, int ring);
1008
1009 /*!
1010         Get the audio device input level.
1011
1012         \return the input level in the range of 0.0f minimum to 1.0f maximum.
1013  */
1014 EXPORT float iaxc_input_level_get();
1015
1016 /*!
1017         Get the audio device output level.
1018
1019         \return the input level in the range of 0.0f minimum to 1.0f maximum.
1020  */
1021 EXPORT float iaxc_output_level_get();
1022
1023 /*!
1024         Sets the audio input level to \a level.
1025         \param level The level in the range from 0.0f (min) to 1.0f (max).
1026 */
1027 EXPORT int iaxc_input_level_set(float level);
1028
1029 /*!
1030         Sets the audio output level to \a level.
1031         \param level The level in the range from 0.0f (min) to 1.0f (max).
1032  */
1033 EXPORT int iaxc_output_level_set(float level);
1034
1035 /*!
1036         A structure describing a sound to IAXClient
1037 */
1038 struct iaxc_sound {
1039         short   *data;           /*!< Sound sample data in 8KHz 16-bit signed format. */
1040         long    len;             /*!< Length of sample in frames. */
1041         int     malloced;        /*!< Should the library free() the data after it is played? */
1042         int     channel;         /*!< The channel used: 0 for output, 1 for ring. */
1043         int     repeat;          /*!< Number of times to repeat (-1 = infinite). */
1044         long    pos;             /*!< \internal use: current play position. */
1045         int     id;              /*!< \internal use: sound ID. */
1046         struct iaxc_sound *next; /*!< \internal use: next in list. */
1047 };
1048
1049 /*!
1050         Play a sound.
1051         \param sound An iaxc_sound structure.
1052         \param ring 0 to play through output device or 1 to play through the "ring" device.
1053
1054         \return The id number of the sound being played
1055 */
1056 EXPORT int iaxc_play_sound(struct iaxc_sound *sound, int ring);
1057
1058 /*!
1059         Stop sound \a id from being played.
1060         \param id The id of a sound to stop as returned from iaxc_play_sound.
1061 */
1062 EXPORT int iaxc_stop_sound(int id);
1063
1064 #define IAXC_FILTER_DENOISE     (1<<0) /*!< Noise reduction filter */
1065 #define IAXC_FILTER_AGC         (1<<1) /*!< Automatic Gain Control */
1066 #define IAXC_FILTER_ECHO        (1<<2) /*!< Echo cancellation filter */
1067 #define IAXC_FILTER_AAGC        (1<<3) /*!< Analog (mixer-based) Automatic Gain Control */
1068 #define IAXC_FILTER_CN          (1<<4) /*!< Send Comfort Noise (CN) frames when silence is detected */
1069
1070 /*!
1071         Returns the set of audio filters being applied.
1072
1073         The IAXC_FILTER_{} defines are used to specify the filters.
1074         \see IAXC_FILTER_DENOISE, IAXC_FILTER_AGC, IAXC_FILTER_ECHO, IAXC_FILTER_AAGC,
1075         IAXC_FILTER_CN
1076  */
1077 EXPORT int iaxc_get_filters(void);
1078
1079 /*!
1080         Sets the current audio filters to apply.
1081         \param filters The combination of all the audio filters to use (IAXC_FILTER_{} defines).
1082
1083         The IAXC_FILTER_{} defines are used to specify the filters.
1084         \see IAXC_FILTER_DENOISE, IAXC_FILTER_AGC, IAXC_FILTER_ECHO, IAXC_FILTER_AAGC,
1085         IAXC_FILTER_CN
1086  */
1087 EXPORT void iaxc_set_filters(int filters);
1088
1089 /*!
1090         Sets speex specific codec settings
1091         \param decode_enhance 1/0  perceptual enhancement for decoder
1092         \param quality: Generally, set either quality (0-9) or bitrate. -1 for "default"
1093         \param bitrate in kbps.  Applies to CBR only; -1 for default.
1094       (overrides "quality" for CBR mode)
1095         \param vbr Variable bitrate mode:  0/1
1096         \param abr mode/rate: 0 for not ABR, bitrate for ABR mode
1097         \param complexity Algorithmic complexity.  Think -N for gzip.
1098       Higher numbers take more CPU for better quality.  3 is
1099       default and good choice.
1100
1101         A good choice is (1,-1,-1,0,8000,3): 8kbps ABR
1102  */
1103 EXPORT void iaxc_set_speex_settings(int decode_enhance, float quality, int bitrate, int vbr, int abr, int complexity);
1104
1105 /*
1106  Functions and flags for setting and getting audio callback preferences
1107   The application can request to receive local/remote, raw/encoded audio
1108   through the callback mechanism. Please note that changing callback
1109   settings will overwrite all previous settings.
1110 */
1111 /*!
1112         Indicates the preference that local audio should be passed to the registered callback in a raw 8KHz 16-bit signed format.
1113 */
1114 #define IAXC_AUDIO_PREF_RECV_LOCAL_RAW      (1 << 0)
1115
1116 /*!
1117         Indicates the preference that local audio should be passed to the registered callback in the current encoded format.
1118 */
1119 #define IAXC_AUDIO_PREF_RECV_LOCAL_ENCODED  (1 << 1)
1120
1121 /*!
1122         Indicates the preference that remote audio should be passed to the registered callback in a raw 8KHz 16-bit signed format.
1123 */
1124 #define IAXC_AUDIO_PREF_RECV_REMOTE_RAW     (1 << 2)
1125
1126 /*!
1127         Indicates the preference that remote audio should be passed to the registered callback in the current encoded format.
1128 */
1129 #define IAXC_AUDIO_PREF_RECV_REMOTE_ENCODED (1 << 3)
1130
1131 /*!
1132         Indicates the preference that sending of audio should be disabled.
1133 */
1134 #define IAXC_AUDIO_PREF_SEND_DISABLE        (1 << 4)
1135
1136 /*!
1137          Returns the various audio delivery preferences.
1138
1139          The preferences are represented using the AIXC_AUDIO_PREF_{} family of defines.
1140 */
1141 EXPORT unsigned int iaxc_get_audio_prefs(void);
1142
1143 /*!
1144         Set the various audio delivery preferences
1145         \param prefs The desired preferences to use. They are represented using the AIXC_AUDIO_PREF_{} family of defines.
1146
1147          \return 0 on success and -1 on error.
1148
1149          \see IAXC_AUDIO_PREF_RECV_LOCAL_RAW, IAXC_AUDIO_PREF_RECV_LOCAL_ENCODED,
1150          IAXC_AUDIO_PREF_RECV_REMOTE_RAW, IAXC_AUDIO_PREF_RECV_REMOTE_ENCODED,
1151          IAXC_AUDIO_PREF_SEND_DISABLE
1152  */
1153 EXPORT int iaxc_set_audio_prefs(unsigned int prefs);
1154
1155 /*!
1156         Get video capture device information.
1157         WARNING: the array pointed to by parameter 'devs' below is owned
1158                  by iaxclient, and may be freed on subsequent calls to
1159                  this function.
1160          \param devs Returns an array of iaxc_video_device structures.
1161                 The array will only be valid until this function is
1162                 called again (if the device list changes), or until
1163                 iaxc is shutdown.
1164          \param nDevs Returns the number of devices in the devs array
1165          \param devId Returns the id of the currently selected video capture device
1166
1167          \return -1 on error, 0 if no change to the device list, 1 if it's been updated
1168  */
1169 EXPORT int iaxc_video_devices_get(struct iaxc_video_device **devs, int *nDevs, int *devId);
1170
1171 /*!
1172         Sets the current video capture device
1173         \param devId The id of the device to use for video capture
1174  */
1175 EXPORT int iaxc_video_device_set(int devId);
1176
1177 /*
1178  * Acceptable range for video rezolution
1179  */
1180 #define IAXC_VIDEO_MAX_WIDTH    704 /*!< Maximum video width */
1181 #define IAXC_VIDEO_MAX_HEIGHT   576 /*!< Maximum video height */
1182 #define IAXC_VIDEO_MIN_WIDTH    80  /*!< Minimum video width */
1183 #define IAXC_VIDEO_MIN_HEIGHT   60  /*!< Minimum video height */
1184
1185 /*
1186  Video callback preferences
1187  The client application can obtain any combination of
1188  remote/local, encoded/raw video through the event callback
1189  mechanism
1190  Use these flags to specify what kind of video do you want to receive
1191  */
1192
1193 /*!
1194         Indicates the preference that local video should be passed to the registered callback in a raw format (typically YUV420).
1195 */
1196 #define IAXC_VIDEO_PREF_RECV_LOCAL_RAW      (1 << 0)
1197
1198 /*!
1199         Indicates the preference that local video should be passed to the registered callback in the current encoded format.
1200 */
1201 #define IAXC_VIDEO_PREF_RECV_LOCAL_ENCODED  (1 << 1)
1202
1203 /*!
1204         Indicates the preference that remote video should be passed to the registered callback in a raw format (typically YUV420).
1205 */
1206 #define IAXC_VIDEO_PREF_RECV_REMOTE_RAW     (1 << 2)
1207
1208 /*!
1209         Indicates the preference that remote video should be passed to the registered callback in the current encoded format.
1210 */
1211 #define IAXC_VIDEO_PREF_RECV_REMOTE_ENCODED (1 << 3)
1212
1213 /*!
1214         Indicates the preference that sending of video should be disabled.
1215 */
1216 #define IAXC_VIDEO_PREF_SEND_DISABLE        (1 << 4)
1217
1218 /*!
1219         This flag specifies that you want raw video in RGB32 format
1220
1221         RGB32: FFRRGGBB aligned 4 bytes per pixel
1222   When this flag is set, iaxclient will convert YUV420 raw video into
1223   RGB32 before passing it to the main app.
1224  */
1225 #define IAXC_VIDEO_PREF_RECV_RGB32          (1 << 5)
1226
1227 /*!
1228   Use this flag to disable/enable camera hardware
1229  */
1230 #define IAXC_VIDEO_PREF_CAPTURE_DISABLE     (1 << 6)
1231
1232 /*!
1233         Returns the current video preferences.
1234
1235          The preferences are represented using the AIXC_VIDEO_PREF_{} family of macros.
1236
1237         \see IAXC_VIDEO_PREF_RECV_LOCAL_RAW, IAXC_VIDEO_PREF_RECV_LOCAL_ENCODED,
1238         IAXC_VIDEO_PREF_RECV_REMOTE_RAW, IAXC_VIDEO_PREF_RECV_REMOTE_ENCODED,
1239         IAXC_VIDEO_PREF_SEND_DISABLE, IAXC_VIDEO_PREF_RECV_RGB32,
1240         IAXC_VIDEO_PREF_CAPTURE_DISABLE
1241 */
1242 EXPORT unsigned int iaxc_get_video_prefs(void);
1243
1244 /*!
1245         Sets the current video preferences.
1246         \param prefs The desired preferences to use. They are represented using the IAXC_VIDEO_PREF_{} family of defines.
1247
1248   Please note that this overwrites all previous preferences. In other
1249   words, a read-modify-write must be done to change a single preference.
1250
1251         \return 0 on success and -1 on error.
1252
1253         \see IAXC_VIDEO_PREF_RECV_LOCAL_RAW, IAXC_VIDEO_PREF_RECV_LOCAL_ENCODED,
1254         IAXC_VIDEO_PREF_RECV_REMOTE_RAW, IAXC_VIDEO_PREF_RECV_REMOTE_ENCODED,
1255         IAXC_VIDEO_PREF_SEND_DISABLE, IAXC_VIDEO_PREF_RECV_RGB32,
1256         IAXC_VIDEO_PREF_CAPTURE_DISABLE
1257  */
1258 EXPORT int iaxc_set_video_prefs(unsigned int prefs);
1259
1260 /*!
1261         Returns the video format settings
1262         \param preferred Receives the single preferred video format
1263         \param allowed Receives the mask of the allowed video formats
1264
1265         \see IAXC_FORMAT_JPEG, IAXC_FORMAT_PNG, IAXC_FORMAT_H261, IAXC_FORMAT_H263,
1266         IAXC_FORMAT_H263_PLUS, IAXC_FORMAT_H264, IAXC_FORMAT_MPEG4,
1267         IAXC_FORMAT_THEORA, IAXC_FORMAT_MAX_VIDEO
1268 */
1269 EXPORT void iaxc_video_format_get_cap(int *preferred, int *allowed);
1270
1271 /*!
1272         Sets the video format capabilities
1273         \param preferred The single preferred video format
1274         \param allowed The mask of the allowed video formats
1275
1276         \see IAXC_FORMAT_JPEG, IAXC_FORMAT_PNG, IAXC_FORMAT_H261, IAXC_FORMAT_H263,
1277         IAXC_FORMAT_H263_PLUS, IAXC_FORMAT_H264, IAXC_FORMAT_MPEG4,
1278         IAXC_FORMAT_THEORA, IAXC_FORMAT_MAX_VIDEO
1279 */
1280 EXPORT void iaxc_video_format_set_cap(int preferred, int allowed);
1281
1282 /*!
1283         Sets the allowed/preferred video formats
1284         \param preferred The single preferred video format
1285         \param allowed The mask of the allowed video formats
1286         \param framerate The video frame rate in fps.
1287         \param bitrate The video bitrate in bps.
1288         \param width The width of the video.
1289         \param height The height of the video.
1290         \param fs The video fragment size.
1291
1292         \see IAXC_FORMAT_JPEG, IAXC_FORMAT_PNG, IAXC_FORMAT_H261, IAXC_FORMAT_H263,
1293         IAXC_FORMAT_H263_PLUS, IAXC_FORMAT_H264, IAXC_FORMAT_MPEG4,
1294         IAXC_FORMAT_THEORA, IAXC_FORMAT_MAX_VIDEO
1295 */
1296 EXPORT void iaxc_video_format_set(int preferred, int allowed, int framerate, int bitrate, int width, int height, int fs);
1297
1298 /*!
1299  Change video params for the current call on the fly
1300  This will destroy the existing encoder and create a new one
1301  use negative values for parameters that should not change
1302  \param framerate The video frame rate in fps.
1303  \param bitrate The video bitrate in bps.
1304  \param width The width of the video.
1305  \param height The height of the video.
1306  \param fs The video fragment size.
1307 */
1308 EXPORT void iaxc_video_params_change(int framerate, int bitrate, int width, int height, int fs);
1309
1310 /*! Set holding frame to be used in some kind of video calls */
1311 EXPORT int iaxc_set_holding_frame(char *);
1312
1313 /*!
1314         Helper function to control use of jitter buffer for video events
1315
1316         \todo make this a video pref, perhaps?
1317 */
1318
1319 EXPORT int iaxc_video_bypass_jitter(int);
1320
1321 /*!
1322   Returns 1 if the default camera is working; 0 otherwise
1323  */
1324 EXPORT int iaxc_is_camera_working();
1325
1326 /*!
1327         Converts a YUV420 image to RGB32
1328         \param width The width of the image
1329         \param height The height of the image
1330         \param src The buffer containing the source image
1331         \param dest The buffer to write the converted image to. The buffer should be \a width * height * 4 bytes in size.
1332
1333         Converts the image based on the forumulas found at
1334         http://en.wikipedia.org/wiki/YUV
1335 */
1336 EXPORT void iaxc_YUV420_to_RGB32(int width, int height, const char *src, char *dest);
1337
1338 /*
1339  * Test mode functionality
1340  * In test mode, iaxclient will do the following:
1341  *   - skip audio and video hardware initialization
1342  *   - wait for outgoing media to be provided by the main application
1343  *   - return incoming media to the calling application if required, via callbacks
1344  *   - not generate any meaningful statistics
1345  * Test mode is designed to be used without a GUI, and with multiple instances of iaxclient
1346  * running on the same machine. However, some applications might actually benefit from having
1347  * this level of control.
1348  * iaxc_set_test_mode() should be called before iaxc_initialize()
1349  */
1350 EXPORT void iaxc_set_test_mode(int);
1351
1352 /*!
1353         \brief Sends compressed audio data to the currently selected call.
1354         \param data compressed audio data
1355         \param size Size of the compressed audio data in bytes
1356         \param samples The number of (uncompressed) samples represented by the compressed audio data. We normally use 20ms packets at a sampling rate of 8000Hz, so this would be 160.
1357
1358         \note Data must be in the audio format that was negotiated for the current call
1359         otherwise bad magic may occur on the recieving side.
1360 */
1361 EXPORT int iaxc_push_audio(void *data, unsigned int size, unsigned int samples);
1362
1363 /*!
1364         \brief Sends compressed video data to the currently selected call.
1365         \param data compressed video data
1366         \param size Size of the compressed video data in bytes
1367         \param fragment If true, split video frames larger than the current fragsize into multiple fragments, otherwise send the data as jumbo frames.
1368
1369         \note Data must be in the video format that was negotiated for the current call
1370         otherwise bad magic may occur on the recieving side.
1371 */
1372 EXPORT int iaxc_push_video(void *data, unsigned int size, int fragment);
1373
1374 /*!
1375         Sets the IAX debug set to \a enable.
1376         \param enable If non-zero enable iax protocol debugging
1377 */
1378 EXPORT void iaxc_debug_iax_set(int enable);
1379
1380 #ifdef __cplusplus
1381 }
1382 #endif
1383
1384 #endif