pjsua.h 307 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560156115621563156415651566156715681569157015711572157315741575157615771578157915801581158215831584158515861587158815891590159115921593159415951596159715981599160016011602160316041605160616071608160916101611161216131614161516161617161816191620162116221623162416251626162716281629163016311632163316341635163616371638163916401641164216431644164516461647164816491650165116521653165416551656165716581659166016611662166316641665166616671668166916701671167216731674167516761677167816791680168116821683168416851686168716881689169016911692169316941695169616971698169917001701170217031704170517061707170817091710171117121713171417151716171717181719172017211722172317241725172617271728172917301731173217331734173517361737173817391740174117421743174417451746174717481749175017511752175317541755175617571758175917601761176217631764176517661767176817691770177117721773177417751776177717781779178017811782178317841785178617871788178917901791179217931794179517961797179817991800180118021803180418051806180718081809181018111812181318141815181618171818181918201821182218231824182518261827182818291830183118321833183418351836183718381839184018411842184318441845184618471848184918501851185218531854185518561857185818591860186118621863186418651866186718681869187018711872187318741875187618771878187918801881188218831884188518861887188818891890189118921893189418951896189718981899190019011902190319041905190619071908190919101911191219131914191519161917191819191920192119221923192419251926192719281929193019311932193319341935193619371938193919401941194219431944194519461947194819491950195119521953195419551956195719581959196019611962196319641965196619671968196919701971197219731974197519761977197819791980198119821983198419851986198719881989199019911992199319941995199619971998199920002001200220032004200520062007200820092010201120122013201420152016201720182019202020212022202320242025202620272028202920302031203220332034203520362037203820392040204120422043204420452046204720482049205020512052205320542055205620572058205920602061206220632064206520662067206820692070207120722073207420752076207720782079208020812082208320842085208620872088208920902091209220932094209520962097209820992100210121022103210421052106210721082109211021112112211321142115211621172118211921202121212221232124212521262127212821292130213121322133213421352136213721382139214021412142214321442145214621472148214921502151215221532154215521562157215821592160216121622163216421652166216721682169217021712172217321742175217621772178217921802181218221832184218521862187218821892190219121922193219421952196219721982199220022012202220322042205220622072208220922102211221222132214221522162217221822192220222122222223222422252226222722282229223022312232223322342235223622372238223922402241224222432244224522462247224822492250225122522253225422552256225722582259226022612262226322642265226622672268226922702271227222732274227522762277227822792280228122822283228422852286228722882289229022912292229322942295229622972298229923002301230223032304230523062307230823092310231123122313231423152316231723182319232023212322232323242325232623272328232923302331233223332334233523362337233823392340234123422343234423452346234723482349235023512352235323542355235623572358235923602361236223632364236523662367236823692370237123722373237423752376237723782379238023812382238323842385238623872388238923902391239223932394239523962397239823992400240124022403240424052406240724082409241024112412241324142415241624172418241924202421242224232424242524262427242824292430243124322433243424352436243724382439244024412442244324442445244624472448244924502451245224532454245524562457245824592460246124622463246424652466246724682469247024712472247324742475247624772478247924802481248224832484248524862487248824892490249124922493249424952496249724982499250025012502250325042505250625072508250925102511251225132514251525162517251825192520252125222523252425252526252725282529253025312532253325342535253625372538253925402541254225432544254525462547254825492550255125522553255425552556255725582559256025612562256325642565256625672568256925702571257225732574257525762577257825792580258125822583258425852586258725882589259025912592259325942595259625972598259926002601260226032604260526062607260826092610261126122613261426152616261726182619262026212622262326242625262626272628262926302631263226332634263526362637263826392640264126422643264426452646264726482649265026512652265326542655265626572658265926602661266226632664266526662667266826692670267126722673267426752676267726782679268026812682268326842685268626872688268926902691269226932694269526962697269826992700270127022703270427052706270727082709271027112712271327142715271627172718271927202721272227232724272527262727272827292730273127322733273427352736273727382739274027412742274327442745274627472748274927502751275227532754275527562757275827592760276127622763276427652766276727682769277027712772277327742775277627772778277927802781278227832784278527862787278827892790279127922793279427952796279727982799280028012802280328042805280628072808280928102811281228132814281528162817281828192820282128222823282428252826282728282829283028312832283328342835283628372838283928402841284228432844284528462847284828492850285128522853285428552856285728582859286028612862286328642865286628672868286928702871287228732874287528762877287828792880288128822883288428852886288728882889289028912892289328942895289628972898289929002901290229032904290529062907290829092910291129122913291429152916291729182919292029212922292329242925292629272928292929302931293229332934293529362937293829392940294129422943294429452946294729482949295029512952295329542955295629572958295929602961296229632964296529662967296829692970297129722973297429752976297729782979298029812982298329842985298629872988298929902991299229932994299529962997299829993000300130023003300430053006300730083009301030113012301330143015301630173018301930203021302230233024302530263027302830293030303130323033303430353036303730383039304030413042304330443045304630473048304930503051305230533054305530563057305830593060306130623063306430653066306730683069307030713072307330743075307630773078307930803081308230833084308530863087308830893090309130923093309430953096309730983099310031013102310331043105310631073108310931103111311231133114311531163117311831193120312131223123312431253126312731283129313031313132313331343135313631373138313931403141314231433144314531463147314831493150315131523153315431553156315731583159316031613162316331643165316631673168316931703171317231733174317531763177317831793180318131823183318431853186318731883189319031913192319331943195319631973198319932003201320232033204320532063207320832093210321132123213321432153216321732183219322032213222322332243225322632273228322932303231323232333234323532363237323832393240324132423243324432453246324732483249325032513252325332543255325632573258325932603261326232633264326532663267326832693270327132723273327432753276327732783279328032813282328332843285328632873288328932903291329232933294329532963297329832993300330133023303330433053306330733083309331033113312331333143315331633173318331933203321332233233324332533263327332833293330333133323333333433353336333733383339334033413342334333443345334633473348334933503351335233533354335533563357335833593360336133623363336433653366336733683369337033713372337333743375337633773378337933803381338233833384338533863387338833893390339133923393339433953396339733983399340034013402340334043405340634073408340934103411341234133414341534163417341834193420342134223423342434253426342734283429343034313432343334343435343634373438343934403441344234433444344534463447344834493450345134523453345434553456345734583459346034613462346334643465346634673468346934703471347234733474347534763477347834793480348134823483348434853486348734883489349034913492349334943495349634973498349935003501350235033504350535063507350835093510351135123513351435153516351735183519352035213522352335243525352635273528352935303531353235333534353535363537353835393540354135423543354435453546354735483549355035513552355335543555355635573558355935603561356235633564356535663567356835693570357135723573357435753576357735783579358035813582358335843585358635873588358935903591359235933594359535963597359835993600360136023603360436053606360736083609361036113612361336143615361636173618361936203621362236233624362536263627362836293630363136323633363436353636363736383639364036413642364336443645364636473648364936503651365236533654365536563657365836593660366136623663366436653666366736683669367036713672367336743675367636773678367936803681368236833684368536863687368836893690369136923693369436953696369736983699370037013702370337043705370637073708370937103711371237133714371537163717371837193720372137223723372437253726372737283729373037313732373337343735373637373738373937403741374237433744374537463747374837493750375137523753375437553756375737583759376037613762376337643765376637673768376937703771377237733774377537763777377837793780378137823783378437853786378737883789379037913792379337943795379637973798379938003801380238033804380538063807380838093810381138123813381438153816381738183819382038213822382338243825382638273828382938303831383238333834383538363837383838393840384138423843384438453846384738483849385038513852385338543855385638573858385938603861386238633864386538663867386838693870387138723873387438753876387738783879388038813882388338843885388638873888388938903891389238933894389538963897389838993900390139023903390439053906390739083909391039113912391339143915391639173918391939203921392239233924392539263927392839293930393139323933393439353936393739383939394039413942394339443945394639473948394939503951395239533954395539563957395839593960396139623963396439653966396739683969397039713972397339743975397639773978397939803981398239833984398539863987398839893990399139923993399439953996399739983999400040014002400340044005400640074008400940104011401240134014401540164017401840194020402140224023402440254026402740284029403040314032403340344035403640374038403940404041404240434044404540464047404840494050405140524053405440554056405740584059406040614062406340644065406640674068406940704071407240734074407540764077407840794080408140824083408440854086408740884089409040914092409340944095409640974098409941004101410241034104410541064107410841094110411141124113411441154116411741184119412041214122412341244125412641274128412941304131413241334134413541364137413841394140414141424143414441454146414741484149415041514152415341544155415641574158415941604161416241634164416541664167416841694170417141724173417441754176417741784179418041814182418341844185418641874188418941904191419241934194419541964197419841994200420142024203420442054206420742084209421042114212421342144215421642174218421942204221422242234224422542264227422842294230423142324233423442354236423742384239424042414242424342444245424642474248424942504251425242534254425542564257425842594260426142624263426442654266426742684269427042714272427342744275427642774278427942804281428242834284428542864287428842894290429142924293429442954296429742984299430043014302430343044305430643074308430943104311431243134314431543164317431843194320432143224323432443254326432743284329433043314332433343344335433643374338433943404341434243434344434543464347434843494350435143524353435443554356435743584359436043614362436343644365436643674368436943704371437243734374437543764377437843794380438143824383438443854386438743884389439043914392439343944395439643974398439944004401440244034404440544064407440844094410441144124413441444154416441744184419442044214422442344244425442644274428442944304431443244334434443544364437443844394440444144424443444444454446444744484449445044514452445344544455445644574458445944604461446244634464446544664467446844694470447144724473447444754476447744784479448044814482448344844485448644874488448944904491449244934494449544964497449844994500450145024503450445054506450745084509451045114512451345144515451645174518451945204521452245234524452545264527452845294530453145324533453445354536453745384539454045414542454345444545454645474548454945504551455245534554455545564557455845594560456145624563456445654566456745684569457045714572457345744575457645774578457945804581458245834584458545864587458845894590459145924593459445954596459745984599460046014602460346044605460646074608460946104611461246134614461546164617461846194620462146224623462446254626462746284629463046314632463346344635463646374638463946404641464246434644464546464647464846494650465146524653465446554656465746584659466046614662466346644665466646674668466946704671467246734674467546764677467846794680468146824683468446854686468746884689469046914692469346944695469646974698469947004701470247034704470547064707470847094710471147124713471447154716471747184719472047214722472347244725472647274728472947304731473247334734473547364737473847394740474147424743474447454746474747484749475047514752475347544755475647574758475947604761476247634764476547664767476847694770477147724773477447754776477747784779478047814782478347844785478647874788478947904791479247934794479547964797479847994800480148024803480448054806480748084809481048114812481348144815481648174818481948204821482248234824482548264827482848294830483148324833483448354836483748384839484048414842484348444845484648474848484948504851485248534854485548564857485848594860486148624863486448654866486748684869487048714872487348744875487648774878487948804881488248834884488548864887488848894890489148924893489448954896489748984899490049014902490349044905490649074908490949104911491249134914491549164917491849194920492149224923492449254926492749284929493049314932493349344935493649374938493949404941494249434944494549464947494849494950495149524953495449554956495749584959496049614962496349644965496649674968496949704971497249734974497549764977497849794980498149824983498449854986498749884989499049914992499349944995499649974998499950005001500250035004500550065007500850095010501150125013501450155016501750185019502050215022502350245025502650275028502950305031503250335034503550365037503850395040504150425043504450455046504750485049505050515052505350545055505650575058505950605061506250635064506550665067506850695070507150725073507450755076507750785079508050815082508350845085508650875088508950905091509250935094509550965097509850995100510151025103510451055106510751085109511051115112511351145115511651175118511951205121512251235124512551265127512851295130513151325133513451355136513751385139514051415142514351445145514651475148514951505151515251535154515551565157515851595160516151625163516451655166516751685169517051715172517351745175517651775178517951805181518251835184518551865187518851895190519151925193519451955196519751985199520052015202520352045205520652075208520952105211521252135214521552165217521852195220522152225223522452255226522752285229523052315232523352345235523652375238523952405241524252435244524552465247524852495250525152525253525452555256525752585259526052615262526352645265526652675268526952705271527252735274527552765277527852795280528152825283528452855286528752885289529052915292529352945295529652975298529953005301530253035304530553065307530853095310531153125313531453155316531753185319532053215322532353245325532653275328532953305331533253335334533553365337533853395340534153425343534453455346534753485349535053515352535353545355535653575358535953605361536253635364536553665367536853695370537153725373537453755376537753785379538053815382538353845385538653875388538953905391539253935394539553965397539853995400540154025403540454055406540754085409541054115412541354145415541654175418541954205421542254235424542554265427542854295430543154325433543454355436543754385439544054415442544354445445544654475448544954505451545254535454545554565457545854595460546154625463546454655466546754685469547054715472547354745475547654775478547954805481548254835484548554865487548854895490549154925493549454955496549754985499550055015502550355045505550655075508550955105511551255135514551555165517551855195520552155225523552455255526552755285529553055315532553355345535553655375538553955405541554255435544554555465547554855495550555155525553555455555556555755585559556055615562556355645565556655675568556955705571557255735574557555765577557855795580558155825583558455855586558755885589559055915592559355945595559655975598559956005601560256035604560556065607560856095610561156125613561456155616561756185619562056215622562356245625562656275628562956305631563256335634563556365637563856395640564156425643564456455646564756485649565056515652565356545655565656575658565956605661566256635664566556665667566856695670567156725673567456755676567756785679568056815682568356845685568656875688568956905691569256935694569556965697569856995700570157025703570457055706570757085709571057115712571357145715571657175718571957205721572257235724572557265727572857295730573157325733573457355736573757385739574057415742574357445745574657475748574957505751575257535754575557565757575857595760576157625763576457655766576757685769577057715772577357745775577657775778577957805781578257835784578557865787578857895790579157925793579457955796579757985799580058015802580358045805580658075808580958105811581258135814581558165817581858195820582158225823582458255826582758285829583058315832583358345835583658375838583958405841584258435844584558465847584858495850585158525853585458555856585758585859586058615862586358645865586658675868586958705871587258735874587558765877587858795880588158825883588458855886588758885889589058915892589358945895589658975898589959005901590259035904590559065907590859095910591159125913591459155916591759185919592059215922592359245925592659275928592959305931593259335934593559365937593859395940594159425943594459455946594759485949595059515952595359545955595659575958595959605961596259635964596559665967596859695970597159725973597459755976597759785979598059815982598359845985598659875988598959905991599259935994599559965997599859996000600160026003600460056006600760086009601060116012601360146015601660176018601960206021602260236024602560266027602860296030603160326033603460356036603760386039604060416042604360446045604660476048604960506051605260536054605560566057605860596060606160626063606460656066606760686069607060716072607360746075607660776078607960806081608260836084608560866087608860896090609160926093609460956096609760986099610061016102610361046105610661076108610961106111611261136114611561166117611861196120612161226123612461256126612761286129613061316132613361346135613661376138613961406141614261436144614561466147614861496150615161526153615461556156615761586159616061616162616361646165616661676168616961706171617261736174617561766177617861796180618161826183618461856186618761886189619061916192619361946195619661976198619962006201620262036204620562066207620862096210621162126213621462156216621762186219622062216222622362246225622662276228622962306231623262336234623562366237623862396240624162426243624462456246624762486249625062516252625362546255625662576258625962606261626262636264626562666267626862696270627162726273627462756276627762786279628062816282628362846285628662876288628962906291629262936294629562966297629862996300630163026303630463056306630763086309631063116312631363146315631663176318631963206321632263236324632563266327632863296330633163326333633463356336633763386339634063416342634363446345634663476348634963506351635263536354635563566357635863596360636163626363636463656366636763686369637063716372637363746375637663776378637963806381638263836384638563866387638863896390639163926393639463956396639763986399640064016402640364046405640664076408640964106411641264136414641564166417641864196420642164226423642464256426642764286429643064316432643364346435643664376438643964406441644264436444644564466447644864496450645164526453645464556456645764586459646064616462646364646465646664676468646964706471647264736474647564766477647864796480648164826483648464856486648764886489649064916492649364946495649664976498649965006501650265036504650565066507650865096510651165126513651465156516651765186519652065216522652365246525652665276528652965306531653265336534653565366537653865396540654165426543654465456546654765486549655065516552655365546555655665576558655965606561656265636564656565666567656865696570657165726573657465756576657765786579658065816582658365846585658665876588658965906591659265936594659565966597659865996600660166026603660466056606660766086609661066116612661366146615661666176618661966206621662266236624662566266627662866296630663166326633663466356636663766386639664066416642664366446645664666476648664966506651665266536654665566566657665866596660666166626663666466656666666766686669667066716672667366746675667666776678667966806681668266836684668566866687668866896690669166926693669466956696669766986699670067016702670367046705670667076708670967106711671267136714671567166717671867196720672167226723672467256726672767286729673067316732673367346735673667376738673967406741674267436744674567466747674867496750675167526753675467556756675767586759676067616762676367646765676667676768676967706771677267736774677567766777677867796780678167826783678467856786678767886789679067916792679367946795679667976798679968006801680268036804680568066807680868096810681168126813681468156816681768186819682068216822682368246825682668276828682968306831683268336834683568366837683868396840684168426843684468456846684768486849685068516852685368546855685668576858685968606861686268636864686568666867686868696870687168726873687468756876687768786879688068816882688368846885688668876888688968906891689268936894689568966897689868996900690169026903690469056906690769086909691069116912691369146915691669176918691969206921692269236924692569266927692869296930693169326933693469356936693769386939694069416942694369446945694669476948694969506951695269536954695569566957695869596960696169626963696469656966696769686969697069716972697369746975697669776978697969806981698269836984698569866987698869896990699169926993699469956996699769986999700070017002700370047005700670077008700970107011701270137014701570167017701870197020702170227023702470257026702770287029703070317032703370347035703670377038703970407041704270437044704570467047704870497050705170527053705470557056705770587059706070617062706370647065706670677068706970707071707270737074707570767077707870797080708170827083708470857086708770887089709070917092709370947095709670977098709971007101710271037104710571067107710871097110711171127113711471157116711771187119712071217122712371247125712671277128712971307131713271337134713571367137713871397140714171427143714471457146714771487149715071517152715371547155715671577158715971607161716271637164716571667167716871697170717171727173717471757176717771787179718071817182718371847185718671877188718971907191719271937194719571967197719871997200720172027203720472057206720772087209721072117212721372147215721672177218721972207221722272237224722572267227722872297230723172327233723472357236723772387239724072417242724372447245724672477248724972507251725272537254725572567257725872597260726172627263726472657266726772687269727072717272727372747275727672777278727972807281728272837284728572867287728872897290729172927293729472957296729772987299730073017302730373047305730673077308730973107311731273137314731573167317731873197320732173227323732473257326732773287329733073317332733373347335733673377338733973407341734273437344734573467347734873497350735173527353735473557356735773587359736073617362736373647365736673677368736973707371737273737374737573767377737873797380738173827383738473857386738773887389739073917392739373947395739673977398739974007401740274037404740574067407740874097410741174127413741474157416741774187419742074217422742374247425742674277428742974307431743274337434743574367437743874397440744174427443744474457446744774487449745074517452745374547455745674577458745974607461746274637464746574667467746874697470747174727473747474757476747774787479748074817482748374847485748674877488748974907491749274937494749574967497749874997500750175027503750475057506750775087509751075117512751375147515751675177518751975207521752275237524752575267527752875297530753175327533753475357536753775387539754075417542754375447545754675477548754975507551755275537554755575567557755875597560756175627563756475657566756775687569757075717572757375747575757675777578757975807581758275837584758575867587758875897590759175927593759475957596759775987599760076017602760376047605760676077608760976107611761276137614761576167617761876197620762176227623762476257626762776287629763076317632763376347635763676377638763976407641764276437644764576467647764876497650765176527653765476557656765776587659766076617662766376647665766676677668766976707671767276737674767576767677767876797680768176827683768476857686768776887689769076917692769376947695769676977698769977007701770277037704770577067707770877097710771177127713771477157716771777187719772077217722772377247725772677277728772977307731773277337734773577367737773877397740774177427743774477457746774777487749775077517752775377547755775677577758775977607761776277637764776577667767776877697770777177727773777477757776777777787779778077817782778377847785778677877788778977907791779277937794779577967797779877997800780178027803780478057806780778087809781078117812781378147815781678177818781978207821782278237824782578267827782878297830783178327833783478357836783778387839784078417842784378447845784678477848784978507851785278537854785578567857785878597860786178627863786478657866786778687869787078717872787378747875787678777878787978807881788278837884788578867887788878897890789178927893789478957896789778987899790079017902790379047905790679077908790979107911791279137914791579167917791879197920792179227923792479257926792779287929793079317932793379347935793679377938793979407941794279437944794579467947794879497950795179527953795479557956795779587959796079617962796379647965796679677968796979707971797279737974797579767977797879797980798179827983798479857986798779887989799079917992799379947995799679977998799980008001800280038004800580068007800880098010801180128013801480158016801780188019802080218022802380248025802680278028802980308031803280338034803580368037803880398040804180428043804480458046804780488049805080518052805380548055805680578058805980608061806280638064806580668067806880698070807180728073807480758076807780788079808080818082808380848085808680878088808980908091809280938094809580968097809880998100810181028103810481058106810781088109811081118112811381148115811681178118811981208121812281238124812581268127812881298130813181328133813481358136813781388139814081418142814381448145814681478148814981508151815281538154815581568157815881598160816181628163816481658166816781688169817081718172817381748175817681778178817981808181818281838184818581868187818881898190819181928193819481958196819781988199820082018202820382048205820682078208820982108211821282138214821582168217821882198220822182228223822482258226822782288229823082318232823382348235823682378238823982408241824282438244824582468247824882498250825182528253825482558256825782588259826082618262826382648265826682678268826982708271827282738274827582768277827882798280828182828283828482858286828782888289829082918292829382948295829682978298829983008301830283038304830583068307830883098310831183128313831483158316831783188319832083218322832383248325832683278328832983308331833283338334833583368337833883398340834183428343834483458346834783488349835083518352835383548355835683578358835983608361836283638364836583668367836883698370837183728373837483758376837783788379838083818382838383848385838683878388838983908391839283938394839583968397839883998400840184028403840484058406840784088409841084118412841384148415841684178418841984208421842284238424842584268427842884298430843184328433843484358436843784388439844084418442844384448445844684478448844984508451845284538454845584568457845884598460846184628463846484658466846784688469847084718472847384748475847684778478847984808481848284838484848584868487848884898490849184928493849484958496849784988499850085018502850385048505850685078508850985108511851285138514851585168517851885198520852185228523852485258526852785288529853085318532853385348535853685378538853985408541854285438544854585468547854885498550855185528553855485558556855785588559856085618562856385648565856685678568856985708571857285738574857585768577857885798580858185828583858485858586858785888589859085918592859385948595859685978598859986008601860286038604860586068607860886098610861186128613861486158616861786188619862086218622862386248625862686278628862986308631863286338634863586368637863886398640864186428643864486458646864786488649865086518652865386548655865686578658865986608661866286638664866586668667866886698670867186728673867486758676867786788679868086818682868386848685868686878688868986908691869286938694869586968697869886998700870187028703870487058706870787088709871087118712871387148715871687178718871987208721872287238724872587268727872887298730873187328733873487358736873787388739874087418742874387448745874687478748874987508751875287538754875587568757875887598760876187628763876487658766876787688769877087718772877387748775877687778778877987808781878287838784878587868787878887898790879187928793879487958796879787988799880088018802880388048805880688078808880988108811881288138814881588168817881888198820882188228823882488258826882788288829883088318832883388348835883688378838883988408841884288438844884588468847884888498850885188528853885488558856885788588859886088618862886388648865886688678868886988708871887288738874887588768877887888798880888188828883888488858886888788888889889088918892889388948895889688978898889989008901890289038904890589068907890889098910891189128913891489158916891789188919892089218922892389248925892689278928892989308931893289338934893589368937893889398940894189428943894489458946894789488949895089518952895389548955895689578958895989608961896289638964896589668967896889698970897189728973897489758976897789788979898089818982898389848985898689878988898989908991899289938994899589968997899889999000900190029003900490059006900790089009901090119012901390149015901690179018901990209021902290239024902590269027902890299030903190329033903490359036903790389039904090419042904390449045904690479048904990509051905290539054905590569057905890599060906190629063906490659066906790689069907090719072907390749075907690779078907990809081908290839084908590869087908890899090909190929093909490959096909790989099910091019102910391049105910691079108910991109111911291139114911591169117911891199120912191229123912491259126912791289129913091319132913391349135
  1. /*
  2. * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)
  3. * Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org>
  4. *
  5. * This program is free software; you can redistribute it and/or modify
  6. * it under the terms of the GNU General Public License as published by
  7. * the Free Software Foundation; either version 2 of the License, or
  8. * (at your option) any later version.
  9. *
  10. * This program is distributed in the hope that it will be useful,
  11. * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  13. * GNU General Public License for more details.
  14. *
  15. * You should have received a copy of the GNU General Public License
  16. * along with this program; if not, write to the Free Software
  17. * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
  18. */
  19. #ifndef __PJSUA_H__
  20. #define __PJSUA_H__
  21. /**
  22. * @file pjsua.h
  23. * @brief PJSUA API.
  24. */
  25. /* Include all PJSIP core headers. */
  26. #include <pjsip.h>
  27. /* Include all PJMEDIA headers. */
  28. #include <pjmedia.h>
  29. /* Include all PJMEDIA-CODEC headers. */
  30. #include <pjmedia-codec.h>
  31. /* Videodev too */
  32. #include <pjmedia_videodev.h>
  33. /* Include all PJSIP-UA headers */
  34. #include <pjsip_ua.h>
  35. /* Include all PJSIP-SIMPLE headers */
  36. #include <pjsip_simple.h>
  37. /* Include all PJNATH headers */
  38. #include <pjnath.h>
  39. /* Include all PJLIB-UTIL headers. */
  40. #include <pjlib-util.h>
  41. /* Include all PJLIB headers. */
  42. #include <pjlib.h>
  43. PJ_BEGIN_DECL
  44. /**
  45. * @defgroup PJSUA_LIB PJSUA API - High Level Softphone API
  46. * @brief Very high level API for constructing SIP UA applications.
  47. * @{
  48. *
  49. * @section pjsua_api_intro A SIP User Agent API for C/C++
  50. *
  51. * PJSUA API is very high level API for constructing SIP multimedia user agent
  52. * applications. It wraps together the signaling and media functionalities
  53. * into an easy to use call API, provides account management, buddy
  54. * management, presence, instant messaging, along with multimedia
  55. * features such as conferencing, file streaming, local playback,
  56. * voice recording, and so on.
  57. *
  58. * @subsection pjsua_for_c_cpp C/C++ Binding
  59. * Application must link with <b>pjsua-lib</b> to use this API. In addition,
  60. * this library depends on the following libraries:
  61. * - <b>pjsip-ua</b>,
  62. * - <b>pjsip-simple</b>,
  63. * - <b>pjsip-core</b>,
  64. * - <b>pjmedia</b>,
  65. * - <b>pjmedia-codec</b>,
  66. * - <b>pjlib-util</b>, and
  67. * - <b>pjlib</b>,
  68. *
  69. * so application must also link with these libraries as well. For more
  70. * information, please refer to
  71. * <A HREF="http://www.pjsip.org/using.htm">Getting Started with PJSIP</A>
  72. * page.
  73. *
  74. * @section pjsua_samples
  75. *
  76. * Few samples are provided:
  77. *
  78. - Simple pjsua app: \src{pjsip-apps/src/samples/simple_pjsua.c} \n
  79. Very simple SIP User Agent with registration, call, and media, using
  80. PJSUA-API, all in under 200 lines of code.
  81. - Pjsua app: \srcdir{pjsip-apps/src/pjsua/} \n
  82. This is the reference implementation for PJSIP and PJMEDIA.
  83. PJSUA is a console based application, designed to be simple enough
  84. to be readble, but powerful enough to demonstrate all features
  85. available in PJSIP and PJMEDIA.\n
  86. * @section root_using_pjsua_lib Using PJSUA API
  87. *
  88. * Please refer to @ref PJSUA_LIB_BASE on how to create and initialize the API.
  89. * And then see the Modules on the bottom of this page for more information
  90. * about specific subject.
  91. */
  92. /*****************************************************************************
  93. * BASE API
  94. */
  95. /**
  96. * @defgroup PJSUA_LIB_BASE PJSUA-API Basic API
  97. * @ingroup PJSUA_LIB
  98. * @brief Basic application creation/initialization, logging configuration, etc.
  99. * @{
  100. *
  101. * The base PJSUA API controls PJSUA creation, initialization, and startup, and
  102. * also provides various auxiliary functions.
  103. *
  104. * @section using_pjsua_lib Using PJSUA Library
  105. *
  106. * @subsection creating_pjsua_lib Creating PJSUA
  107. *
  108. * Before anything else, application must create PJSUA by calling
  109. * #pjsua_create().
  110. * This, among other things, will initialize PJLIB, which is crucial before
  111. * any PJLIB functions can be called, PJLIB-UTIL, and create a SIP endpoint.
  112. *
  113. * After this function is called, application can create a memory pool (with
  114. * #pjsua_pool_create()) and read configurations from command line or file to
  115. * build the settings to initialize PJSUA below.
  116. *
  117. * @subsection init_pjsua_lib Initializing PJSUA
  118. *
  119. * After PJSUA is created, application can initialize PJSUA by calling
  120. * #pjsua_init(). This function takes several optional configuration settings
  121. * in the argument, if application wants to set them.
  122. *
  123. * @subsubsection init_pjsua_lib_c_cpp PJSUA-LIB Initialization (in C)
  124. * Sample code to initialize PJSUA in C code:
  125. \code
  126. #include <pjsua-lib/pjsua.h>
  127. #define THIS_FILE __FILE__
  128. static pj_status_t app_init(void)
  129. {
  130. pjsua_config ua_cfg;
  131. pjsua_logging_config log_cfg;
  132. pjsua_media_config media_cfg;
  133. pj_status_t status;
  134. // Must create pjsua before anything else!
  135. status = pjsua_create();
  136. if (status != PJ_SUCCESS) {
  137. pjsua_perror(THIS_FILE, "Error initializing pjsua", status);
  138. return status;
  139. }
  140. // Initialize configs with default settings.
  141. pjsua_config_default(&ua_cfg);
  142. pjsua_logging_config_default(&log_cfg);
  143. pjsua_media_config_default(&media_cfg);
  144. // At the very least, application would want to override
  145. // the call callbacks in pjsua_config:
  146. ua_cfg.cb.on_incoming_call = ...
  147. ua_cfg.cb.on_call_state = ..
  148. ...
  149. // Customize other settings (or initialize them from application specific
  150. // configuration file):
  151. ...
  152. // Initialize pjsua
  153. status = pjsua_init(&ua_cfg, &log_cfg, &media_cfg);
  154. if (status != PJ_SUCCESS) {
  155. pjsua_perror(THIS_FILE, "Error initializing pjsua", status);
  156. return status;
  157. }
  158. .
  159. ...
  160. }
  161. \endcode
  162. *
  163. *
  164. * @subsection other_init_pjsua_lib Other Initialization
  165. *
  166. * After PJSUA is initialized with #pjsua_init(), application will normally
  167. * need/want to perform the following tasks:
  168. *
  169. * - create SIP transport with #pjsua_transport_create(). Application would
  170. * to call #pjsua_transport_create() for each transport types that it
  171. * wants to support (for example, UDP, TCP, and TLS). Please see
  172. * @ref PJSUA_LIB_TRANSPORT section for more info.
  173. * - create one or more SIP accounts with #pjsua_acc_add() or
  174. * #pjsua_acc_add_local(). The SIP account is used for registering with
  175. * the SIP server, if any. Please see @ref PJSUA_LIB_ACC for more info.
  176. * - add one or more buddies with #pjsua_buddy_add(). Please see
  177. * @ref PJSUA_LIB_BUDDY section for more info.
  178. * - optionally configure the sound device, codec settings, and other
  179. * media settings. Please see @ref PJSUA_LIB_MEDIA for more info.
  180. *
  181. *
  182. * @subsection starting_pjsua_lib Starting PJSUA
  183. *
  184. * After all initializations have been done, application must call
  185. * #pjsua_start() to start PJSUA. This function will check that all settings
  186. * have been properly configured, and apply default settings when they haven't,
  187. * or report error status when it is unable to recover from missing settings.
  188. *
  189. * Most settings can be changed during run-time. For example, application
  190. * may add, modify, or delete accounts, buddies, or change media settings
  191. * during run-time.
  192. *
  193. * @subsubsection starting_pjsua_lib_c C Example for Starting PJSUA
  194. * Sample code:
  195. \code
  196. static pj_status_t app_run(void)
  197. {
  198. pj_status_t status;
  199. // Start pjsua
  200. status = pjsua_start();
  201. if (status != PJ_SUCCESS) {
  202. pjsua_destroy();
  203. pjsua_perror(THIS_FILE, "Error starting pjsua", status);
  204. return status;
  205. }
  206. // Run application loop
  207. while (1) {
  208. char choice[10];
  209. printf("Select menu: ");
  210. fgets(choice, sizeof(choice), stdin);
  211. ...
  212. }
  213. }
  214. \endcode
  215. */
  216. /** Constant to identify invalid ID for all sorts of IDs. */
  217. enum pjsua_invalid_id_const_
  218. {
  219. PJSUA_INVALID_ID = -1
  220. };
  221. /** Disabled features temporarily for media reorganization */
  222. #define DISABLED_FOR_TICKET_1185 0
  223. /** Call identification */
  224. typedef int pjsua_call_id;
  225. /** Account identification */
  226. typedef int pjsua_acc_id;
  227. /** Buddy identification */
  228. typedef int pjsua_buddy_id;
  229. /** File player identification */
  230. typedef int pjsua_player_id;
  231. /** File recorder identification */
  232. typedef int pjsua_recorder_id;
  233. /** Conference port identification */
  234. typedef int pjsua_conf_port_id;
  235. /** Opaque declaration for server side presence subscription */
  236. typedef struct pjsua_srv_pres pjsua_srv_pres;
  237. /** Forward declaration for pjsua_msg_data */
  238. typedef struct pjsua_msg_data pjsua_msg_data;
  239. /** Forward declaration for pj_stun_resolve_result */
  240. typedef struct pj_stun_resolve_result pj_stun_resolve_result;
  241. /**
  242. * Initial memory block for PJSUA.
  243. */
  244. #ifndef PJSUA_POOL_LEN
  245. # define PJSUA_POOL_LEN 1000
  246. #endif
  247. /**
  248. * Memory increment for PJSUA.
  249. */
  250. #ifndef PJSUA_POOL_INC
  251. # define PJSUA_POOL_INC 1000
  252. #endif
  253. /**
  254. * Initial memory block for PJSUA account.
  255. */
  256. #ifndef PJSUA_POOL_LEN_ACC
  257. # define PJSUA_POOL_LEN_ACC 512
  258. #endif
  259. /**
  260. * Memory increment for PJSUA account.
  261. */
  262. #ifndef PJSUA_POOL_INC_ACC
  263. # define PJSUA_POOL_INC_ACC 256
  264. #endif
  265. /**
  266. * Maximum proxies in account.
  267. */
  268. #ifndef PJSUA_ACC_MAX_PROXIES
  269. # define PJSUA_ACC_MAX_PROXIES 8
  270. #endif
  271. /**
  272. * Default value of SRTP mode usage. Valid values are PJMEDIA_SRTP_DISABLED,
  273. * PJMEDIA_SRTP_OPTIONAL, and PJMEDIA_SRTP_MANDATORY.
  274. */
  275. #ifndef PJSUA_DEFAULT_USE_SRTP
  276. #define PJSUA_DEFAULT_USE_SRTP PJMEDIA_SRTP_DISABLED
  277. #endif
  278. /**
  279. * Default value of secure signaling requirement for SRTP.
  280. * Valid values are:
  281. * 0: SRTP does not require secure signaling
  282. * 1: SRTP requires secure transport such as TLS
  283. * 2: SRTP requires secure end-to-end transport (SIPS)
  284. */
  285. #ifndef PJSUA_DEFAULT_SRTP_SECURE_SIGNALING
  286. #define PJSUA_DEFAULT_SRTP_SECURE_SIGNALING 1
  287. #endif
  288. /**
  289. * Controls whether PJSUA-LIB should add ICE media feature tag
  290. * parameter (the ";+sip.ice" parameter) to Contact header if ICE
  291. * is enabled in the config.
  292. *
  293. * Default: 1
  294. */
  295. #ifndef PJSUA_ADD_ICE_TAGS
  296. # define PJSUA_ADD_ICE_TAGS 1
  297. #endif
  298. /**
  299. * Timeout value used to acquire mutex lock on a particular call.
  300. *
  301. * Default: 2000 ms
  302. */
  303. #ifndef PJSUA_ACQUIRE_CALL_TIMEOUT
  304. # define PJSUA_ACQUIRE_CALL_TIMEOUT 2000
  305. #endif
  306. /**
  307. * Is video enabled.
  308. */
  309. #ifndef PJSUA_HAS_VIDEO
  310. # define PJSUA_HAS_VIDEO PJMEDIA_HAS_VIDEO
  311. #endif
  312. /**
  313. * Interval between two keyframe requests, in milliseconds.
  314. *
  315. * Default: 3000 ms
  316. */
  317. #ifndef PJSUA_VID_REQ_KEYFRAME_INTERVAL
  318. # define PJSUA_VID_REQ_KEYFRAME_INTERVAL 3000
  319. #endif
  320. /**
  321. * Specify whether timer heap events will be polled by a separate worker
  322. * thread. If this is set/enabled, a worker thread will be dedicated to
  323. * poll timer heap events only, and the rest worker thread(s) will poll
  324. * ioqueue/network events only.
  325. *
  326. * Note that if worker thread count setting (i.e: pjsua_config.thread_cnt)
  327. * is set to zero, this setting will be ignored.
  328. *
  329. * Default: 0 (disabled)
  330. */
  331. #ifndef PJSUA_SEPARATE_WORKER_FOR_TIMER
  332. # define PJSUA_SEPARATE_WORKER_FOR_TIMER 0
  333. #endif
  334. /**
  335. * Specify whether pjsua should disable automatically sending initial
  336. * answer 100/Trying for incoming calls. If disabled, application can
  337. * later send 100/Trying if it wishes using pjsua_call_answer().
  338. *
  339. * Default: 0 (automatic sending enabled)
  340. */
  341. #ifndef PJSUA_DISABLE_AUTO_SEND_100
  342. # define PJSUA_DISABLE_AUTO_SEND_100 0
  343. #endif
  344. /**
  345. * Default options that will be passed when creating ice transport.
  346. * See #pjmedia_transport_ice_options.
  347. */
  348. #ifndef PJSUA_ICE_TRANSPORT_OPTION
  349. # define PJSUA_ICE_TRANSPORT_OPTION 0
  350. #endif
  351. /**
  352. * Interval of checking for any new ICE candidate when trickle ICE is active.
  353. * Trickle ICE gathers local ICE candidates, such as STUN and TURN candidates,
  354. * in the background, while SDP offer/answer negotiation is being performed.
  355. * Later, when any new ICE candidate is found, the endpoint will convey
  356. * the candidate to the remote endpoint via SIP INFO.
  357. *
  358. * Default: 100 ms
  359. */
  360. #ifndef PJSUA_TRICKLE_ICE_NEW_CAND_CHECK_INTERVAL
  361. # define PJSUA_TRICKLE_ICE_NEW_CAND_CHECK_INTERVAL 100
  362. #endif
  363. /**
  364. * Specify if PJSUA should check for merged requests as per RFC 3261 section
  365. * 8.2.2.2. If a merged request is detected, PJSUA will automatically reply
  366. * with a 482 - Loop Detected.
  367. *
  368. * Default: 1 (enabled)
  369. */
  370. #ifndef PJSUA_DETECT_MERGED_REQUESTS
  371. # define PJSUA_DETECT_MERGED_REQUESTS 1
  372. #endif
  373. /**
  374. * This enumeration represents pjsua state.
  375. */
  376. typedef enum pjsua_state
  377. {
  378. /**
  379. * The library has not been initialized.
  380. */
  381. PJSUA_STATE_NULL,
  382. /**
  383. * After pjsua_create() is called but before pjsua_init() is called.
  384. */
  385. PJSUA_STATE_CREATED,
  386. /**
  387. * After pjsua_init() is called but before pjsua_start() is called.
  388. */
  389. PJSUA_STATE_INIT,
  390. /**
  391. * After pjsua_start() is called but before everything is running.
  392. */
  393. PJSUA_STATE_STARTING,
  394. /**
  395. * After pjsua_start() is called and before pjsua_destroy() is called.
  396. */
  397. PJSUA_STATE_RUNNING,
  398. /**
  399. * After pjsua_destroy() is called but before the function returns.
  400. */
  401. PJSUA_STATE_CLOSING
  402. } pjsua_state;
  403. /**
  404. * Logging configuration, which can be (optionally) specified when calling
  405. * #pjsua_init(). Application must call #pjsua_logging_config_default() to
  406. * initialize this structure with the default values.
  407. */
  408. typedef struct pjsua_logging_config
  409. {
  410. /**
  411. * Log incoming and outgoing SIP message? Yes!
  412. */
  413. pj_bool_t msg_logging;
  414. /**
  415. * Input verbosity level. Value 5 is reasonable.
  416. */
  417. unsigned level;
  418. /**
  419. * Verbosity level for console. Value 4 is reasonable.
  420. */
  421. unsigned console_level;
  422. /**
  423. * Log decoration.
  424. */
  425. unsigned decor;
  426. /**
  427. * Optional log filename.
  428. */
  429. pj_str_t log_filename;
  430. /**
  431. * Additional flags to be given to #pj_file_open() when opening
  432. * the log file. By default, the flag is PJ_O_WRONLY. Application
  433. * may set PJ_O_APPEND here so that logs are appended to existing
  434. * file instead of overwriting it.
  435. *
  436. * Default is 0.
  437. */
  438. unsigned log_file_flags;
  439. /**
  440. * Optional callback function to be called to write log to
  441. * application specific device. This function will be called for
  442. * log messages on input verbosity level.
  443. */
  444. void (*cb)(int level, const char *data, int len);
  445. } pjsua_logging_config;
  446. /**
  447. * Use this function to initialize logging config.
  448. *
  449. * @param cfg The logging config to be initialized.
  450. */
  451. PJ_DECL(void) pjsua_logging_config_default(pjsua_logging_config *cfg);
  452. /**
  453. * Use this function to duplicate logging config.
  454. *
  455. * @param pool Pool to use.
  456. * @param dst Destination config.
  457. * @param src Source config.
  458. */
  459. PJ_DECL(void) pjsua_logging_config_dup(pj_pool_t *pool,
  460. pjsua_logging_config *dst,
  461. const pjsua_logging_config *src);
  462. /**
  463. * Structure to be passed on MWI callback.
  464. */
  465. typedef struct pjsua_mwi_info
  466. {
  467. pjsip_evsub *evsub; /**< Event subscription session, for
  468. reference. */
  469. pjsip_rx_data *rdata; /**< The received NOTIFY request. */
  470. } pjsua_mwi_info;
  471. /**
  472. * Structure to be passed on registration callback.
  473. */
  474. typedef struct pjsua_reg_info
  475. {
  476. struct pjsip_regc_cbparam *cbparam; /**< Parameters returned by
  477. registration callback. */
  478. pjsip_regc *regc; /**< Client registration
  479. structure. */
  480. pj_bool_t renew; /**< Non-zero for registration and
  481. zero for unregistration. */
  482. } pjsua_reg_info;
  483. /**
  484. * Media stream info.
  485. */
  486. typedef struct pjsua_stream_info
  487. {
  488. /** Media type of this stream. */
  489. pjmedia_type type;
  490. /** Stream info (union). */
  491. union {
  492. /** Audio stream info */
  493. pjmedia_stream_info aud;
  494. /** Video stream info */
  495. pjmedia_vid_stream_info vid;
  496. } info;
  497. } pjsua_stream_info;
  498. /**
  499. * Media stream statistic.
  500. */
  501. typedef struct pjsua_stream_stat
  502. {
  503. /** RTCP statistic. */
  504. pjmedia_rtcp_stat rtcp;
  505. /** Jitter buffer statistic. */
  506. pjmedia_jb_state jbuf;
  507. } pjsua_stream_stat;
  508. /**
  509. * Structure to be passed to on stream precreate callback.
  510. * See on_stream_precreate().
  511. */
  512. typedef struct pjsua_on_stream_precreate_param
  513. {
  514. /**
  515. * Stream index in the media session, read-only.
  516. */
  517. unsigned stream_idx;
  518. /**
  519. * Parameters that the stream will be created from.
  520. */
  521. pjsua_stream_info stream_info;
  522. } pjsua_on_stream_precreate_param;
  523. /**
  524. * Structure to be passed to on stream created callback.
  525. * See on_stream_created2().
  526. */
  527. typedef struct pjsua_on_stream_created_param
  528. {
  529. /**
  530. * The audio media stream, read-only.
  531. */
  532. pjmedia_stream *stream;
  533. /**
  534. * Stream index in the audio media session, read-only.
  535. */
  536. unsigned stream_idx;
  537. /**
  538. * Specify if PJSUA should take ownership of the port returned in
  539. * the port parameter below. If set to PJ_TRUE,
  540. * pjmedia_port_destroy() will be called on the port when it is
  541. * no longer needed.
  542. *
  543. * Default: PJ_FALSE
  544. */
  545. pj_bool_t destroy_port;
  546. /**
  547. * On input, it specifies the audio media port of the stream. Application
  548. * may modify this pointer to point to different media port to be
  549. * registered to the conference bridge.
  550. */
  551. pjmedia_port *port;
  552. } pjsua_on_stream_created_param;
  553. /**
  554. * Enumeration of media transport state types.
  555. */
  556. typedef enum pjsua_med_tp_st
  557. {
  558. /** Null, this is the state before media transport is created. */
  559. PJSUA_MED_TP_NULL,
  560. /**
  561. * Just before media transport is created, which can finish
  562. * asynchronously later.
  563. */
  564. PJSUA_MED_TP_CREATING,
  565. /** Media transport creation is completed, but not initialized yet. */
  566. PJSUA_MED_TP_IDLE,
  567. /** Initialized (media_create() has been called). */
  568. PJSUA_MED_TP_INIT,
  569. /** Running (media_start() has been called). */
  570. PJSUA_MED_TP_RUNNING,
  571. /** Disabled (transport is initialized, but media is being disabled). */
  572. PJSUA_MED_TP_DISABLED
  573. } pjsua_med_tp_st;
  574. /**
  575. * Structure to be passed on media transport state callback.
  576. */
  577. typedef struct pjsua_med_tp_state_info
  578. {
  579. /**
  580. * The media index.
  581. */
  582. unsigned med_idx;
  583. /**
  584. * The media transport state
  585. */
  586. pjsua_med_tp_st state;
  587. /**
  588. * The last error code related to the media transport state.
  589. */
  590. pj_status_t status;
  591. /**
  592. * Optional SIP error code.
  593. */
  594. int sip_err_code;
  595. /**
  596. * Optional extended info, the content is specific for each transport type.
  597. */
  598. void *ext_info;
  599. } pjsua_med_tp_state_info;
  600. /**
  601. * Type of callback to be called when media transport state is changed.
  602. *
  603. * @param call_id The call ID.
  604. * @param info The media transport state info.
  605. *
  606. * @return The callback must return PJ_SUCCESS at the moment.
  607. */
  608. typedef pj_status_t
  609. (*pjsua_med_tp_state_cb)(pjsua_call_id call_id,
  610. const pjsua_med_tp_state_info *info);
  611. /**
  612. * Typedef of callback to be registered to #pjsua_resolve_stun_servers()
  613. * and to be called when STUN resolution completes.
  614. */
  615. typedef void (*pj_stun_resolve_cb)(const pj_stun_resolve_result *result);
  616. /**
  617. * This enumeration specifies the options for custom media transport creation.
  618. */
  619. typedef enum pjsua_create_media_transport_flag
  620. {
  621. /**
  622. * This flag indicates that the media transport must also close its
  623. * "member" or "child" transport when pjmedia_transport_close() is
  624. * called. If this flag is not specified, then the media transport
  625. * must not call pjmedia_transport_close() of its member transport.
  626. */
  627. PJSUA_MED_TP_CLOSE_MEMBER = 1
  628. } pjsua_create_media_transport_flag;
  629. /**
  630. * Specify SRTP media transport settings.
  631. */
  632. typedef struct pjsua_srtp_opt
  633. {
  634. /**
  635. * Specify the number of crypto suite settings. If set to zero, all
  636. * available cryptos will be enabled. Note that available crypto names
  637. * can be enumerated using pjmedia_srtp_enum_crypto().
  638. *
  639. * Default is zero.
  640. */
  641. unsigned crypto_count;
  642. /**
  643. * Specify individual crypto suite setting and its priority order.
  644. *
  645. * Notes for DTLS-SRTP keying:
  646. * - Currently only supports these cryptos: AES_CM_128_HMAC_SHA1_80,
  647. * AES_CM_128_HMAC_SHA1_32, AEAD_AES_256_GCM, and AEAD_AES_128_GCM.
  648. * - SRTP key is not configurable.
  649. */
  650. pjmedia_srtp_crypto crypto[PJMEDIA_SRTP_MAX_CRYPTOS];
  651. /**
  652. * Specify the number of enabled keying methods. If set to zero, all
  653. * keyings will be enabled. Maximum value is PJMEDIA_SRTP_MAX_KEYINGS.
  654. * Note that available keying methods can be enumerated using
  655. * pjmedia_srtp_enum_keying().
  656. *
  657. * Default is zero (all keyings are enabled with priority order:
  658. * SDES, DTLS-SRTP).
  659. */
  660. unsigned keying_count;
  661. /**
  662. * Specify enabled keying methods and its priority order. Keying method
  663. * with higher priority will be given earlier chance to process the SDP,
  664. * for example as currently only one keying is supported in the SDP offer,
  665. * keying with first priority will be likely used in the SDP offer.
  666. */
  667. pjmedia_srtp_keying_method keying[PJMEDIA_SRTP_KEYINGS_COUNT];
  668. } pjsua_srtp_opt;
  669. /**
  670. * This enumeration specifies the contact rewrite method.
  671. */
  672. typedef enum pjsua_contact_rewrite_method
  673. {
  674. /**
  675. * The Contact update will be done by sending unregistration
  676. * to the currently registered Contact, while simultaneously sending new
  677. * registration (with different Call-ID) for the updated Contact.
  678. */
  679. PJSUA_CONTACT_REWRITE_UNREGISTER = 1,
  680. /**
  681. * The Contact update will be done in a single, current
  682. * registration session, by removing the current binding (by setting its
  683. * Contact's expires parameter to zero) and adding a new Contact binding,
  684. * all done in a single request.
  685. */
  686. PJSUA_CONTACT_REWRITE_NO_UNREG = 2,
  687. /**
  688. * The Contact update will be done when receiving any registration final
  689. * response. If this flag is not specified, contact update will only be
  690. * done upon receiving 2xx response. This flag MUST be used with
  691. * PJSUA_CONTACT_REWRITE_UNREGISTER or PJSUA_CONTACT_REWRITE_NO_UNREG
  692. * above to specify how the Contact update should be performed when
  693. * receiving 2xx response.
  694. */
  695. PJSUA_CONTACT_REWRITE_ALWAYS_UPDATE = 4
  696. } pjsua_contact_rewrite_method;
  697. /**
  698. * This enumeration specifies the operation when handling IP change.
  699. */
  700. typedef enum pjsua_ip_change_op {
  701. /**
  702. * Hasn't start ip change process.
  703. */
  704. PJSUA_IP_CHANGE_OP_NULL,
  705. /**
  706. * The restart listener process.
  707. */
  708. PJSUA_IP_CHANGE_OP_SHUTDOWN_TP,
  709. /**
  710. * The restart listener process.
  711. */
  712. PJSUA_IP_CHANGE_OP_RESTART_LIS,
  713. /**
  714. * The shutdown transport process.
  715. */
  716. PJSUA_IP_CHANGE_OP_ACC_SHUTDOWN_TP,
  717. /**
  718. * The update contact process.
  719. */
  720. PJSUA_IP_CHANGE_OP_ACC_UPDATE_CONTACT,
  721. /**
  722. * The hanging up call process.
  723. */
  724. PJSUA_IP_CHANGE_OP_ACC_HANGUP_CALLS,
  725. /**
  726. * The re-INVITE call process.
  727. */
  728. PJSUA_IP_CHANGE_OP_ACC_REINVITE_CALLS,
  729. /**
  730. * The ip change process has completed.
  731. */
  732. PJSUA_IP_CHANGE_OP_COMPLETED
  733. } pjsua_ip_change_op;
  734. /**
  735. * This will contain the information of the callback \a on_ip_change_progress.
  736. */
  737. typedef union pjsua_ip_change_op_info {
  738. /**
  739. * The information from listener restart operation.
  740. */
  741. struct {
  742. int transport_id;
  743. } lis_restart;
  744. /**
  745. * The information from shutdown transport.
  746. */
  747. struct {
  748. int acc_id;
  749. } acc_shutdown_tp;
  750. /**
  751. * The information from updating contact.
  752. */
  753. struct {
  754. pjsua_acc_id acc_id;
  755. pj_bool_t is_register; /**< SIP Register if PJ_TRUE. */
  756. int code; /**< SIP status code received. */
  757. } acc_update_contact;
  758. /**
  759. * The information from hanging up call operation.
  760. */
  761. struct {
  762. pjsua_acc_id acc_id;
  763. pjsua_call_id call_id;
  764. } acc_hangup_calls;
  765. /**
  766. * The information from re-Invite call operation.
  767. */
  768. struct {
  769. pjsua_acc_id acc_id;
  770. pjsua_call_id call_id;
  771. } acc_reinvite_calls;
  772. } pjsua_ip_change_op_info;
  773. /**
  774. * This enumeration specifies DTMF method.
  775. */
  776. typedef enum pjsua_dtmf_method {
  777. /**
  778. * Send DTMF using RFC2833.
  779. */
  780. PJSUA_DTMF_METHOD_RFC2833,
  781. /**
  782. * Send DTMF using SIP INFO.
  783. * Notes:
  784. * - This method is not finalized in any standard/rfc, however it is
  785. * commonly used.
  786. * - Warning: in case the remote doesn't support SIP INFO, response might
  787. * not be sent and the sender will deal this as timeout and disconnect
  788. * the call.
  789. */
  790. PJSUA_DTMF_METHOD_SIP_INFO
  791. } pjsua_dtmf_method;
  792. /**
  793. * Constant to specify unknown duration in \a pjsua_dtmf_info and
  794. * \a pjsua_dtmf_event.
  795. */
  796. #define PJSUA_UNKNOWN_DTMF_DURATION ((unsigned)-1)
  797. /**
  798. * This will contain the information of the callback \a on_dtmf_digit2.
  799. */
  800. typedef struct pjsua_dtmf_info {
  801. /**
  802. * The method used to send DTMF.
  803. */
  804. pjsua_dtmf_method method;
  805. /**
  806. * DTMF ASCII digit.
  807. */
  808. unsigned digit;
  809. /**
  810. * DTMF signal duration. If the duration is unknown, this value is set to
  811. * PJSUA_UNKNOWN_DTMF_DURATION.
  812. */
  813. unsigned duration;
  814. } pjsua_dtmf_info;
  815. /**
  816. * This will contain the information of the callback \a on_dtmf_event.
  817. */
  818. typedef struct pjsua_dtmf_event {
  819. /**
  820. * The method used to send DTMF.
  821. */
  822. pjsua_dtmf_method method;
  823. /**
  824. * The timestamp identifying the begin of the event. Timestamp units are
  825. * expressed in milliseconds.
  826. * Note that this value should only be used to compare multiple events
  827. * received via the same method relatively to each other, as the time-base
  828. * is randomized.
  829. */
  830. unsigned timestamp;
  831. /**
  832. * DTMF ASCII digit.
  833. */
  834. unsigned digit;
  835. /**
  836. * DTMF signal duration in milliseconds. Interpretation of the duration
  837. * depends on the flag PJMEDIA_STREAM_DTMF_IS_END.
  838. * If PJMEDIA_STREAM_DTMF_IS_END is set, this contains the total duration
  839. * of the DTMF signal or PJSUA_UNKNOWN_DTMF_DURATION if the duration is
  840. * unknown.
  841. * If PJMEDIA_STREAM_DTMF_IS_END is not set, this contains the duration
  842. * of the DTMF signal received up to this point in time.
  843. * A duration of "0" indicates an infinitely long duration.
  844. */
  845. unsigned duration;
  846. /**
  847. * Flags indicating additional information about the DTMF event.
  848. * If PJMEDIA_STREAM_DTMF_IS_UPDATE is set, the event was already
  849. * indicated earlier. The new indication contains an updated event
  850. * duration.
  851. * If PJMEDIA_STREAM_DTMF_IS_END is set, the event has ended and this
  852. * indication contains the final event duration. Note that end
  853. * indications might get lost. Hence it is not guaranteed to receive
  854. * an event with PJMEDIA_STREAM_DTMF_IS_END for every event.
  855. */
  856. unsigned flags;
  857. } pjsua_dtmf_event;
  858. /**
  859. * Call settings.
  860. */
  861. typedef struct pjsua_call_setting
  862. {
  863. /**
  864. * Bitmask of #pjsua_call_flag constants.
  865. *
  866. * Default: PJSUA_CALL_INCLUDE_DISABLED_MEDIA
  867. */
  868. unsigned flag;
  869. /**
  870. * This flag controls what methods to request keyframe are allowed on
  871. * the call. Value is bitmask of #pjsua_vid_req_keyframe_method.
  872. *
  873. * Default: (PJSUA_VID_REQ_KEYFRAME_SIP_INFO |
  874. * PJSUA_VID_REQ_KEYFRAME_RTCP_PLI)
  875. */
  876. unsigned req_keyframe_method;
  877. /**
  878. * Number of simultaneous active audio streams for this call. Setting
  879. * this to zero will disable audio in this call.
  880. *
  881. * Default: 1
  882. */
  883. unsigned aud_cnt;
  884. /**
  885. * Number of simultaneous active video streams for this call. Setting
  886. * this to zero will disable video in this call.
  887. *
  888. * Default: 1 (if video feature is enabled, otherwise it is zero)
  889. */
  890. unsigned vid_cnt;
  891. /**
  892. * Media direction. This setting will only be used if the flag
  893. * PJSUA_CALL_SET_MEDIA_DIR is set, and it will persist for subsequent
  894. * offers or answers.
  895. * For example, a media that is set as PJMEDIA_DIR_ENCODING can only
  896. * mark the stream in the SDP as sendonly or inactive, but will not
  897. * become sendrecv in subsequent offers and answers.
  898. * Application can update the media direction in any API or callback
  899. * that accepts pjsua_call_setting as a parameter, such as via
  900. * pjsua_call_reinvite/update() or in on_call_rx_offer/reinvite()
  901. * callback.
  902. *
  903. * The index of the media dir will correspond to the provisional media
  904. * in pjsua_call_info.prov_media.
  905. * For offers that involve adding new medias (such as initial offer),
  906. * the index will correspond to all new audio media first, then video.
  907. * For example, for a new call with 2 audios and 1 video, media_dir[0]
  908. * and media_dir[1] will be for the audios, and media_dir[2] video.
  909. *
  910. * Default: PJMEDIA_DIR_ENCODING_DECODING
  911. */
  912. pjmedia_dir media_dir[PJMEDIA_MAX_SDP_MEDIA];
  913. /**
  914. * Custom Call-ID to be sent out with outgoing INVITE. Overrides
  915. * default Call-ID generated by dialog.
  916. *
  917. * Note: It is up to the developer to verify uniqueness of the
  918. * Call-ID as there will be no verification. The developer must
  919. * change the Call-ID between calls creating a unique id for each
  920. * outgoing call.
  921. *
  922. * This setting will only be used when creating a new outgoing call
  923. * via pjsua_call_make_call().
  924. */
  925. pj_str_t custom_call_id;
  926. } pjsua_call_setting;
  927. /**
  928. * This will contain the information passed from the callback
  929. * \a pjsua_on_rejected_incoming_call_cb.
  930. */
  931. typedef struct pjsua_on_rejected_incoming_call_param {
  932. /**
  933. * The incoming call id. This will be set to PJSUA_INVALID_ID when there is
  934. * no available call slot at the time.
  935. */
  936. pjsua_call_id call_id;
  937. /**
  938. * Local URI.
  939. */
  940. pj_str_t local_info;
  941. /**
  942. * Remote URI.
  943. */
  944. pj_str_t remote_info;
  945. /**
  946. * Rejection code.
  947. */
  948. int st_code;
  949. /**
  950. * Rejection text.
  951. */
  952. pj_str_t st_text;
  953. /**
  954. * The original INVITE message, if it's not available this will be set
  955. * to NULL.
  956. */
  957. pjsip_rx_data *rdata;
  958. /**
  959. * Internal.
  960. */
  961. struct {
  962. char local_info[PJSIP_MAX_URL_SIZE];
  963. char remote_info[PJSIP_MAX_URL_SIZE];
  964. } buf_;
  965. } pjsua_on_rejected_incoming_call_param;
  966. /**
  967. * Type of callback to be called when incoming call is rejected.
  968. *
  969. * @param param The rejected call information.
  970. *
  971. */
  972. typedef void (*pjsua_on_rejected_incoming_call_cb)(
  973. const pjsua_on_rejected_incoming_call_param *param);
  974. /**
  975. * This structure describes application callback to receive various event
  976. * notification from PJSUA-API. All of these callbacks are OPTIONAL,
  977. * although definitely application would want to implement some of
  978. * the important callbacks (such as \a on_incoming_call).
  979. */
  980. typedef struct pjsua_callback
  981. {
  982. /**
  983. * Notify application when call state has changed.
  984. * Application may then query the call info to get the
  985. * detail call states by calling pjsua_call_get_info() function.
  986. *
  987. * @param call_id The call index.
  988. * @param e Event which causes the call state to change.
  989. */
  990. void (*on_call_state)(pjsua_call_id call_id, pjsip_event *e);
  991. /**
  992. * Notify application on incoming call.
  993. *
  994. * @param acc_id The account which match the incoming call.
  995. * @param call_id The call id that has just been created for
  996. * the call.
  997. * @param rdata The incoming INVITE request.
  998. */
  999. void (*on_incoming_call)(pjsua_acc_id acc_id, pjsua_call_id call_id,
  1000. pjsip_rx_data *rdata);
  1001. /**
  1002. * This is a general notification callback which is called whenever
  1003. * a transaction within the call has changed state. Application can
  1004. * implement this callback for example to monitor the state of
  1005. * outgoing requests, or to answer unhandled incoming requests
  1006. * (such as INFO) with a final response.
  1007. *
  1008. * @param call_id Call identification.
  1009. * @param tsx The transaction which has changed state.
  1010. * @param e Transaction event that caused the state change.
  1011. */
  1012. void (*on_call_tsx_state)(pjsua_call_id call_id,
  1013. pjsip_transaction *tsx,
  1014. pjsip_event *e);
  1015. /**
  1016. * Notify application when media state in the call has changed.
  1017. * Normal application would need to implement this callback, e.g.
  1018. * to connect the call's media to sound device. When ICE is used,
  1019. * this callback will also be called to report ICE negotiation
  1020. * failure. When DTLS-SRTP is used, this callback will also be called
  1021. * to report DTLS negotiation failure.
  1022. *
  1023. * @param call_id The call index.
  1024. */
  1025. void (*on_call_media_state)(pjsua_call_id call_id);
  1026. /**
  1027. * Notify application when a call has just created a local SDP (for
  1028. * initial or subsequent SDP offer/answer). Application can implement
  1029. * this callback to modify the SDP, before it is being sent and/or
  1030. * negotiated with remote SDP, for example to apply per account/call
  1031. * basis codecs priority or to add custom/proprietary SDP attributes.
  1032. *
  1033. * @param call_id The call index.
  1034. * @param sdp The SDP has just been created.
  1035. * @param pool The pool instance, application should use this pool
  1036. * to modify the SDP.
  1037. * @param rem_sdp The remote SDP, will be NULL if local is SDP offerer.
  1038. */
  1039. void (*on_call_sdp_created)(pjsua_call_id call_id,
  1040. pjmedia_sdp_session *sdp,
  1041. pj_pool_t *pool,
  1042. const pjmedia_sdp_session *rem_sdp);
  1043. /**
  1044. * Notify application when an audio media session is about to be created
  1045. * (as opposed to on_stream_created() and on_stream_created2() which are
  1046. * called *after* the session has been created). The application may change
  1047. * some stream info parameter values, i.e: jb_init, jb_min_pre, jb_max_pre,
  1048. * jb_max, use_ka, rtcp_sdes_bye_disabled, jb_discard_algo (audio),
  1049. * rx_event_pt (audio), codec_param->enc_fmt (video).
  1050. *
  1051. * @param call_id Call identification.
  1052. * @param param The on stream precreate callback parameter.
  1053. */
  1054. void (*on_stream_precreate)(pjsua_call_id call_id,
  1055. pjsua_on_stream_precreate_param *param);
  1056. /**
  1057. * Notify application when audio media session is created and before it is
  1058. * registered to the conference bridge. Application may return different
  1059. * audio media port if it has added media processing port to the stream.
  1060. * This media port then will be added to the conference bridge instead.
  1061. *
  1062. * Note: if implemented, on_stream_created2() callback will be called
  1063. * instead of this one.
  1064. *
  1065. * @param call_id Call identification.
  1066. * @param strm Audio media stream.
  1067. * @param stream_idx Stream index in the audio media session.
  1068. * @param p_port On input, it specifies the audio media port of the
  1069. * stream. Application may modify this pointer to
  1070. * point to different media port to be registered
  1071. * to the conference bridge.
  1072. */
  1073. void (*on_stream_created)(pjsua_call_id call_id,
  1074. pjmedia_stream *strm,
  1075. unsigned stream_idx,
  1076. pjmedia_port **p_port);
  1077. /**
  1078. * Notify application when audio media session is created and before it is
  1079. * registered to the conference bridge. Application may return different
  1080. * audio media port if it has added media processing port to the stream.
  1081. * This media port then will be added to the conference bridge instead.
  1082. *
  1083. * @param call_id Call identification.
  1084. * @param param The on stream created callback parameter.
  1085. */
  1086. void (*on_stream_created2)(pjsua_call_id call_id,
  1087. pjsua_on_stream_created_param *param);
  1088. /**
  1089. * Notify application when audio media session has been unregistered from
  1090. * the conference bridge and about to be destroyed.
  1091. *
  1092. * @param call_id Call identification.
  1093. * @param strm Audio media stream.
  1094. * @param stream_idx Stream index in the audio media session.
  1095. */
  1096. void (*on_stream_destroyed)(pjsua_call_id call_id,
  1097. pjmedia_stream *strm,
  1098. unsigned stream_idx);
  1099. /**
  1100. * Notify application upon incoming DTMF digits using RFC 2833 payload
  1101. * formats. This callback will not be called if app implements \a
  1102. * on_dtmf_digit2() or \a on_dtmf_event().
  1103. *
  1104. * @param call_id The call index.
  1105. * @param digit DTMF ASCII digit.
  1106. */
  1107. void (*on_dtmf_digit)(pjsua_call_id call_id, int digit);
  1108. /**
  1109. * Notify application upon incoming DTMF digits using the method specified
  1110. * in \a pjsua_dtmf_method. This callback will not be called if app
  1111. * implements \a on_dtmf_event().
  1112. *
  1113. * @param call_id The call index.
  1114. * @param info The DTMF info.
  1115. */
  1116. void (*on_dtmf_digit2)(pjsua_call_id call_id, const pjsua_dtmf_info *info);
  1117. /**
  1118. * Notify application upon incoming DTMF digits using the method specified
  1119. * in \a pjsua_dtmf_method. Includes additional information about events
  1120. * received via RTP.
  1121. *
  1122. * @param call_id The call index.
  1123. * @param event The DTMF event.
  1124. */
  1125. void (*on_dtmf_event)(pjsua_call_id call_id,
  1126. const pjsua_dtmf_event *event);
  1127. /**
  1128. * Notify application on call being transferred (i.e. REFER is received).
  1129. * Application can decide to accept/reject transfer request
  1130. * by setting the code (default is 202). When this callback
  1131. * is not defined, the default behavior is to accept the
  1132. * transfer. See also on_call_transfer_request2() callback for
  1133. * the version with \a pjsua_call_setting in the argument list.
  1134. *
  1135. * @param call_id The call index.
  1136. * @param dst The destination where the call will be
  1137. * transferred to.
  1138. * @param code Status code to be returned for the call transfer
  1139. * request. On input, it contains status code 202.
  1140. */
  1141. void (*on_call_transfer_request)(pjsua_call_id call_id,
  1142. const pj_str_t *dst,
  1143. pjsip_status_code *code);
  1144. /**
  1145. * Notify application on call being transferred (i.e. REFER is received).
  1146. * Application can decide to accept/reject transfer request
  1147. * by setting the code (default is 202). When this callback
  1148. * is not defined, the default behavior is to accept the
  1149. * transfer.
  1150. *
  1151. * @param call_id The call index.
  1152. * @param dst The destination where the call will be
  1153. * transferred to.
  1154. * @param code Status code to be returned for the call transfer
  1155. * request. On input, it contains status code 202.
  1156. * @param opt The current call setting, application can update
  1157. * this setting for the call being transferred.
  1158. */
  1159. void (*on_call_transfer_request2)(pjsua_call_id call_id,
  1160. const pj_str_t *dst,
  1161. pjsip_status_code *code,
  1162. pjsua_call_setting *opt);
  1163. /**
  1164. * Notify application of the status of previously sent call
  1165. * transfer request. Application can monitor the status of the
  1166. * call transfer request, for example to decide whether to
  1167. * terminate existing call.
  1168. *
  1169. * @param call_id Call ID.
  1170. * @param st_code Status progress of the transfer request.
  1171. * @param st_text Status progress text.
  1172. * @param final If non-zero, no further notification will
  1173. * be reported. The st_code specified in
  1174. * this callback is the final status.
  1175. * @param p_cont Initially will be set to non-zero, application
  1176. * can set this to FALSE if it no longer wants
  1177. * to receie further notification (for example,
  1178. * after it hangs up the call).
  1179. */
  1180. void (*on_call_transfer_status)(pjsua_call_id call_id,
  1181. int st_code,
  1182. const pj_str_t *st_text,
  1183. pj_bool_t final,
  1184. pj_bool_t *p_cont);
  1185. /**
  1186. * Notify application about incoming INVITE with Replaces header.
  1187. * Application may reject the request by setting non-2xx code.
  1188. * See also on_call_replace_request2() callback for the version
  1189. * with \a pjsua_call_setting in the argument list.
  1190. *
  1191. * @param call_id The call ID to be replaced.
  1192. * @param rdata The incoming INVITE request to replace the call.
  1193. * @param st_code Status code to be set by application. Application
  1194. * should only return a final status (200-699).
  1195. * @param st_text Optional status text to be set by application.
  1196. */
  1197. void (*on_call_replace_request)(pjsua_call_id call_id,
  1198. pjsip_rx_data *rdata,
  1199. int *st_code,
  1200. pj_str_t *st_text);
  1201. /**
  1202. * Notify application about incoming INVITE with Replaces header.
  1203. * Application may reject the request by setting non-2xx code.
  1204. *
  1205. * @param call_id The call ID to be replaced.
  1206. * @param rdata The incoming INVITE request to replace the call.
  1207. * @param st_code Status code to be set by application. Application
  1208. * should only return a final status (200-699).
  1209. * @param st_text Optional status text to be set by application.
  1210. * @param opt The current call setting, application can update
  1211. * this setting for the call being replaced.
  1212. */
  1213. void (*on_call_replace_request2)(pjsua_call_id call_id,
  1214. pjsip_rx_data *rdata,
  1215. int *st_code,
  1216. pj_str_t *st_text,
  1217. pjsua_call_setting *opt);
  1218. /**
  1219. * Notify application that an existing call has been replaced with
  1220. * a new call. This happens when PJSUA-API receives incoming INVITE
  1221. * request with Replaces header.
  1222. *
  1223. * After this callback is called, normally PJSUA-API will disconnect
  1224. * \a old_call_id and establish \a new_call_id.
  1225. *
  1226. * @param old_call_id Existing call which to be replaced with the
  1227. * new call.
  1228. * @param new_call_id The new call.
  1229. * @param rdata The incoming INVITE with Replaces request.
  1230. */
  1231. void (*on_call_replaced)(pjsua_call_id old_call_id,
  1232. pjsua_call_id new_call_id);
  1233. /**
  1234. * Notify application when call has received new offer from remote
  1235. * (i.e. re-INVITE/UPDATE with SDP is received, or from the
  1236. * INVITE response in the case that the initial outgoing INVITE
  1237. * has no SDP). Application can
  1238. * decide to accept/reject the offer by setting the code (default
  1239. * is 200). If the offer is accepted, application can update the
  1240. * call setting to be applied in the answer. When this callback is
  1241. * not defined, the default behavior is to accept the offer using
  1242. * current call setting.
  1243. *
  1244. * Note: this callback may not be called if \a on_call_rx_reinvite()
  1245. * is implemented.
  1246. *
  1247. * @param call_id The call index.
  1248. * @param offer The new offer received.
  1249. * @param reserved Reserved param, currently not used.
  1250. * @param code Status code to be returned for answering the
  1251. * offer. On input, it contains status code 200.
  1252. * Currently, valid values are only 200 and 488.
  1253. * @param opt The current call setting, application can update
  1254. * this setting for answering the offer.
  1255. */
  1256. void (*on_call_rx_offer)(pjsua_call_id call_id,
  1257. const pjmedia_sdp_session *offer,
  1258. void *reserved,
  1259. pjsip_status_code *code,
  1260. pjsua_call_setting *opt);
  1261. /**
  1262. * Notify application when call has received a re-INVITE with offer
  1263. * from the peer. It allows more fine-grained control over the response
  1264. * to a re-INVITE. If application sets async to PJ_TRUE, it can send
  1265. * the reply manually using the function #pjsua_call_answer_with_sdp().
  1266. * Otherwise, by default the re-INVITE will be answered automatically
  1267. * after the callback returns.
  1268. *
  1269. * Currently, this callback is only called for re-INVITE with
  1270. * SDP, but app should be prepared to handle the case of re-INVITE
  1271. * without SDP.
  1272. *
  1273. * Remarks: If manually answering at a later timing, application may
  1274. * need to monitor on_call_tsx_state() callback to check whether
  1275. * the re-INVITE is already answered automatically with 487 due to
  1276. * being cancelled.
  1277. *
  1278. * Note: on_call_rx_offer() will still be called after this callback,
  1279. * but only if async is PJ_FALSE and code is 200.
  1280. *
  1281. * @param call_id The call index.
  1282. * @param offer Remote offer.
  1283. * @param rdata The received re-INVITE request.
  1284. * @param reserved Reserved param, currently not used.
  1285. * @param async On input, it is PJ_FALSE. Set to PJ_TRUE if
  1286. * app wants to manually answer the re-INVITE.
  1287. * @param code Status code to be returned for answering the
  1288. * offer. On input, it contains status code 200.
  1289. * Currently, valid values are only 200 and 488.
  1290. * @param opt The current call setting, application can update
  1291. * this setting for answering the offer.
  1292. */
  1293. void (*on_call_rx_reinvite)(pjsua_call_id call_id,
  1294. const pjmedia_sdp_session *offer,
  1295. pjsip_rx_data *rdata,
  1296. void *reserved,
  1297. pj_bool_t *async,
  1298. pjsip_status_code *code,
  1299. pjsua_call_setting *opt);
  1300. /**
  1301. * Notify application when call has received INVITE with no SDP offer.
  1302. * Application can update the call setting (e.g: add audio/video), or
  1303. * enable/disable codecs, or update other media session settings from
  1304. * within the callback, however, as mandated by the standard (RFC3261
  1305. * section 14.2), it must ensure that the update overlaps with the
  1306. * existing media session (in codecs, transports, or other parameters)
  1307. * that require support from the peer, this is to avoid the need for
  1308. * the peer to reject the offer.
  1309. *
  1310. * When this callback is not defined, the default behavior is to send
  1311. * SDP offer using current active media session (with all enabled codecs
  1312. * on each media type).
  1313. *
  1314. * @param call_id The call index.
  1315. * @param reserved Reserved param, currently not used.
  1316. * @param opt The current call setting, application can update
  1317. * this setting for generating the offer.
  1318. */
  1319. void (*on_call_tx_offer)(pjsua_call_id call_id,
  1320. void *reserved,
  1321. pjsua_call_setting *opt);
  1322. /**
  1323. * Notify application when registration or unregistration has been
  1324. * initiated. Note that this only notifies the initial registration
  1325. * and unregistration. Once registration session is active, subsequent
  1326. * refresh will not cause this callback to be called.
  1327. *
  1328. * @param acc_id The account ID.
  1329. * @param renew Non-zero for registration and zero for
  1330. * unregistration.
  1331. */
  1332. void (*on_reg_started)(pjsua_acc_id acc_id, pj_bool_t renew);
  1333. /**
  1334. * This is the alternative version of the \a on_reg_started() callback with
  1335. * \a pjsua_reg_info argument.
  1336. *
  1337. * @param acc_id The account ID.
  1338. * @param info The registration info.
  1339. */
  1340. void (*on_reg_started2)(pjsua_acc_id acc_id,
  1341. pjsua_reg_info *info);
  1342. /**
  1343. * Notify application when registration status has changed.
  1344. * Application may then query the account info to get the
  1345. * registration details.
  1346. *
  1347. * @param acc_id The account ID.
  1348. */
  1349. void (*on_reg_state)(pjsua_acc_id acc_id);
  1350. /**
  1351. * Notify application when registration status has changed.
  1352. * Application may inspect the registration info to get the
  1353. * registration status details.
  1354. *
  1355. * @param acc_id The account ID.
  1356. * @param info The registration info.
  1357. */
  1358. void (*on_reg_state2)(pjsua_acc_id acc_id, pjsua_reg_info *info);
  1359. /**
  1360. * Notification when incoming SUBSCRIBE request is received. Application
  1361. * may use this callback to authorize the incoming subscribe request
  1362. * (e.g. ask user permission if the request should be granted).
  1363. *
  1364. * If this callback is not implemented, all incoming presence subscription
  1365. * requests will be accepted.
  1366. *
  1367. * If this callback is implemented, application has several choices on
  1368. * what to do with the incoming request:
  1369. * - it may reject the request immediately by specifying non-200 class
  1370. * final response in the \a code argument.
  1371. * - it may immediately accept the request by specifying 200 as the
  1372. * \a code argument. This is the default value if application doesn't
  1373. * set any value to the \a code argument. In this case, the library
  1374. * will automatically send NOTIFY request upon returning from this
  1375. * callback.
  1376. * - it may delay the processing of the request, for example to request
  1377. * user permission whether to accept or reject the request. In this
  1378. * case, the application MUST set the \a code argument to 202, then
  1379. * IMMEDIATELY calls #pjsua_pres_notify() with state
  1380. * PJSIP_EVSUB_STATE_PENDING and later calls #pjsua_pres_notify()
  1381. * again to accept or reject the subscription request.
  1382. *
  1383. * Any \a code other than 200 and 202 will be treated as 200.
  1384. *
  1385. * Application MUST return from this callback immediately (e.g. it must
  1386. * not block in this callback while waiting for user confirmation).
  1387. *
  1388. * @param srv_pres Server presence subscription instance. If
  1389. * application delays the acceptance of the request,
  1390. * it will need to specify this object when calling
  1391. * #pjsua_pres_notify().
  1392. * @param acc_id Account ID most appropriate for this request.
  1393. * @param buddy_id ID of the buddy matching the sender of the
  1394. * request, if any, or PJSUA_INVALID_ID if no
  1395. * matching buddy is found.
  1396. * @param from The From URI of the request.
  1397. * @param rdata The incoming request.
  1398. * @param code The status code to respond to the request. The
  1399. * default value is 200. Application may set this
  1400. * to other final status code to accept or reject
  1401. * the request.
  1402. * @param reason The reason phrase to respond to the request.
  1403. * @param msg_data If the application wants to send additional
  1404. * headers in the response, it can put it in this
  1405. * parameter.
  1406. */
  1407. void (*on_incoming_subscribe)(pjsua_acc_id acc_id,
  1408. pjsua_srv_pres *srv_pres,
  1409. pjsua_buddy_id buddy_id,
  1410. const pj_str_t *from,
  1411. pjsip_rx_data *rdata,
  1412. pjsip_status_code *code,
  1413. pj_str_t *reason,
  1414. pjsua_msg_data *msg_data);
  1415. /**
  1416. * Notification when server side subscription state has changed.
  1417. * This callback is optional as application normally does not need
  1418. * to do anything to maintain server side presence subscription.
  1419. *
  1420. * @param acc_id The account ID.
  1421. * @param srv_pres Server presence subscription object.
  1422. * @param remote_uri Remote URI string.
  1423. * @param state New subscription state.
  1424. * @param event PJSIP event that triggers the state change.
  1425. */
  1426. void (*on_srv_subscribe_state)(pjsua_acc_id acc_id,
  1427. pjsua_srv_pres *srv_pres,
  1428. const pj_str_t *remote_uri,
  1429. pjsip_evsub_state state,
  1430. pjsip_event *event);
  1431. /**
  1432. * Notify application when the buddy state has changed.
  1433. * Application may then query the buddy into to get the details.
  1434. *
  1435. * @param buddy_id The buddy id.
  1436. */
  1437. void (*on_buddy_state)(pjsua_buddy_id buddy_id);
  1438. /**
  1439. * Notify application when the buddy dialog state has changed.
  1440. * Application may then query the buddy into to get the details.
  1441. *
  1442. * @param buddy_id The buddy id.
  1443. */
  1444. void (*on_buddy_dlg_event_state)(pjsua_buddy_id buddy_id);
  1445. /**
  1446. * Notify application when the state of client subscription session
  1447. * associated with a buddy has changed. Application may use this
  1448. * callback to retrieve more detailed information about the state
  1449. * changed event.
  1450. *
  1451. * @param buddy_id The buddy id.
  1452. * @param sub Event subscription session.
  1453. * @param event The event which triggers state change event.
  1454. */
  1455. void (*on_buddy_evsub_state)(pjsua_buddy_id buddy_id,
  1456. pjsip_evsub *sub,
  1457. pjsip_event *event);
  1458. /**
  1459. * Notify application when the state of client subscription session
  1460. * associated with a buddy dialog state has changed. Application
  1461. * may use this callback to retrieve more detailed information about the
  1462. * state changed event.
  1463. *
  1464. * @param buddy_id The buddy id.
  1465. * @param sub Event subscription session.
  1466. * @param event The event which triggers state change event.
  1467. */
  1468. void (*on_buddy_evsub_dlg_event_state)(pjsua_buddy_id buddy_id,
  1469. pjsip_evsub *sub,
  1470. pjsip_event *event);
  1471. /**
  1472. * Notify application on incoming pager (i.e. MESSAGE request).
  1473. * Argument call_id will be -1 if MESSAGE request is not related to an
  1474. * existing call.
  1475. *
  1476. * See also \a on_pager2() callback for the version with \a pjsip_rx_data
  1477. * passed as one of the argument.
  1478. *
  1479. * @param call_id Containts the ID of the call where the IM was
  1480. * sent, or PJSUA_INVALID_ID if the IM was sent
  1481. * outside call context.
  1482. * @param from URI of the sender.
  1483. * @param to URI of the destination message.
  1484. * @param contact The Contact URI of the sender, if present.
  1485. * @param mime_type MIME type of the message.
  1486. * @param body The message content.
  1487. */
  1488. void (*on_pager)(pjsua_call_id call_id, const pj_str_t *from,
  1489. const pj_str_t *to, const pj_str_t *contact,
  1490. const pj_str_t *mime_type, const pj_str_t *body);
  1491. /**
  1492. * This is the alternative version of the \a on_pager() callback with
  1493. * \a pjsip_rx_data argument.
  1494. *
  1495. * @param call_id Containts the ID of the call where the IM was
  1496. * sent, or PJSUA_INVALID_ID if the IM was sent
  1497. * outside call context.
  1498. * @param from URI of the sender.
  1499. * @param to URI of the destination message.
  1500. * @param contact The Contact URI of the sender, if present.
  1501. * @param mime_type MIME type of the message.
  1502. * @param body The message content.
  1503. * @param rdata The incoming MESSAGE request.
  1504. * @param acc_id Account ID most suitable for this message.
  1505. */
  1506. void (*on_pager2)(pjsua_call_id call_id, const pj_str_t *from,
  1507. const pj_str_t *to, const pj_str_t *contact,
  1508. const pj_str_t *mime_type, const pj_str_t *body,
  1509. pjsip_rx_data *rdata, pjsua_acc_id acc_id);
  1510. /**
  1511. * Notify application about the delivery status of outgoing pager
  1512. * request. See also on_pager_status2() callback for the version with
  1513. * \a pjsip_rx_data in the argument list.
  1514. *
  1515. * @param call_id Containts the ID of the call where the IM was
  1516. * sent, or PJSUA_INVALID_ID if the IM was sent
  1517. * outside call context.
  1518. * @param to Destination URI.
  1519. * @param body Message body.
  1520. * @param user_data Arbitrary data that was specified when sending
  1521. * IM message.
  1522. * @param status Delivery status.
  1523. * @param reason Delivery status reason.
  1524. */
  1525. void (*on_pager_status)(pjsua_call_id call_id,
  1526. const pj_str_t *to,
  1527. const pj_str_t *body,
  1528. void *user_data,
  1529. pjsip_status_code status,
  1530. const pj_str_t *reason);
  1531. /**
  1532. * Notify application about the delivery status of outgoing pager
  1533. * request.
  1534. *
  1535. * @param call_id Containts the ID of the call where the IM was
  1536. * sent, or PJSUA_INVALID_ID if the IM was sent
  1537. * outside call context.
  1538. * @param to Destination URI.
  1539. * @param body Message body.
  1540. * @param user_data Arbitrary data that was specified when sending
  1541. * IM message.
  1542. * @param status Delivery status.
  1543. * @param reason Delivery status reason.
  1544. * @param tdata The original MESSAGE request.
  1545. * @param rdata The incoming MESSAGE response, or NULL if the
  1546. * message transaction fails because of time out
  1547. * or transport error.
  1548. * @param acc_id Account ID from this the instant message was
  1549. * send.
  1550. */
  1551. void (*on_pager_status2)(pjsua_call_id call_id,
  1552. const pj_str_t *to,
  1553. const pj_str_t *body,
  1554. void *user_data,
  1555. pjsip_status_code status,
  1556. const pj_str_t *reason,
  1557. pjsip_tx_data *tdata,
  1558. pjsip_rx_data *rdata,
  1559. pjsua_acc_id acc_id);
  1560. /**
  1561. * Notify application about typing indication.
  1562. *
  1563. * @param call_id Containts the ID of the call where the IM was
  1564. * sent, or PJSUA_INVALID_ID if the IM was sent
  1565. * outside call context.
  1566. * @param from URI of the sender.
  1567. * @param to URI of the destination message.
  1568. * @param contact The Contact URI of the sender, if present.
  1569. * @param is_typing Non-zero if peer is typing, or zero if peer
  1570. * has stopped typing a message.
  1571. */
  1572. void (*on_typing)(pjsua_call_id call_id, const pj_str_t *from,
  1573. const pj_str_t *to, const pj_str_t *contact,
  1574. pj_bool_t is_typing);
  1575. /**
  1576. * Notify application about typing indication.
  1577. *
  1578. * @param call_id Containts the ID of the call where the IM was
  1579. * sent, or PJSUA_INVALID_ID if the IM was sent
  1580. * outside call context.
  1581. * @param from URI of the sender.
  1582. * @param to URI of the destination message.
  1583. * @param contact The Contact URI of the sender, if present.
  1584. * @param is_typing Non-zero if peer is typing, or zero if peer
  1585. * has stopped typing a message.
  1586. * @param rdata The received request.
  1587. * @param acc_id Account ID most suitable for this message.
  1588. */
  1589. void (*on_typing2)(pjsua_call_id call_id, const pj_str_t *from,
  1590. const pj_str_t *to, const pj_str_t *contact,
  1591. pj_bool_t is_typing, pjsip_rx_data *rdata,
  1592. pjsua_acc_id acc_id);
  1593. /**
  1594. * Callback when the library has finished performing NAT type
  1595. * detection.
  1596. *
  1597. * @param res NAT detection result.
  1598. */
  1599. void (*on_nat_detect)(const pj_stun_nat_detect_result *res);
  1600. /**
  1601. * This callback is called when the call is about to resend the
  1602. * INVITE request to the specified target, following the previously
  1603. * received redirection response.
  1604. *
  1605. * Application may accept the redirection to the specified target,
  1606. * reject this target only and make the session continue to try the next
  1607. * target in the list if such target exists, stop the whole
  1608. * redirection process altogether and cause the session to be
  1609. * disconnected, or defer the decision to ask for user confirmation.
  1610. *
  1611. * This callback is optional. If this callback is not implemented,
  1612. * the default behavior is to NOT follow the redirection response.
  1613. *
  1614. * @param call_id The call ID.
  1615. * @param target The current target to be tried.
  1616. * @param e The event that caused this callback to be called.
  1617. * This could be the receipt of 3xx response, or
  1618. * 4xx/5xx response received for the INVITE sent to
  1619. * subsequent targets, or NULL if this callback is
  1620. * called from within #pjsua_call_process_redirect()
  1621. * context.
  1622. *
  1623. * @return Action to be performed for the target. Set this
  1624. * parameter to one of the value below:
  1625. * - PJSIP_REDIRECT_ACCEPT: immediately accept the
  1626. * redirection. When set, the call will immediately
  1627. * resend INVITE request to the target.
  1628. * - PJSIP_REDIRECT_ACCEPT_REPLACE: immediately accept
  1629. * the redirection and replace the To header with the
  1630. * current target. When set, the call will immediately
  1631. * resend INVITE request to the target.
  1632. * - PJSIP_REDIRECT_REJECT: immediately reject this
  1633. * target. The call will continue retrying with
  1634. * next target if present, or disconnect the call
  1635. * if there is no more target to try.
  1636. * - PJSIP_REDIRECT_STOP: stop the whole redirection
  1637. * process and immediately disconnect the call. The
  1638. * on_call_state() callback will be called with
  1639. * PJSIP_INV_STATE_DISCONNECTED state immediately
  1640. * after this callback returns.
  1641. * - PJSIP_REDIRECT_PENDING: set to this value if
  1642. * no decision can be made immediately (for example
  1643. * to request confirmation from user). Application
  1644. * then MUST call #pjsua_call_process_redirect()
  1645. * to either accept or reject the redirection upon
  1646. * getting user decision.
  1647. */
  1648. pjsip_redirect_op (*on_call_redirected)(pjsua_call_id call_id,
  1649. const pjsip_uri *target,
  1650. const pjsip_event *e);
  1651. /**
  1652. * This callback is called when message waiting indication subscription
  1653. * state has changed. Application can then query the subscription state
  1654. * by calling #pjsip_evsub_get_state().
  1655. *
  1656. * @param acc_id The account ID.
  1657. * @param evsub The subscription instance.
  1658. */
  1659. void (*on_mwi_state)(pjsua_acc_id acc_id, pjsip_evsub *evsub);
  1660. /**
  1661. * This callback is called when a NOTIFY request for message summary /
  1662. * message waiting indication is received.
  1663. *
  1664. * @param acc_id The account ID.
  1665. * @param mwi_info Structure containing details of the event,
  1666. * including the received NOTIFY request in the
  1667. * \a rdata field.
  1668. */
  1669. void (*on_mwi_info)(pjsua_acc_id acc_id, pjsua_mwi_info *mwi_info);
  1670. /**
  1671. * This callback is called when transport state is changed. See also
  1672. * #pjsip_tp_state_callback.
  1673. */
  1674. pjsip_tp_state_callback on_transport_state;
  1675. /**
  1676. * This callback is called when media transport state is changed. See
  1677. * also #pjsua_med_tp_state_cb.
  1678. */
  1679. pjsua_med_tp_state_cb on_call_media_transport_state;
  1680. /**
  1681. * This callback is called to report error in ICE media transport.
  1682. * Currently it is used to report TURN Refresh error.
  1683. *
  1684. * @param index Transport index.
  1685. * @param op Operation which trigger the failure.
  1686. * @param status Error status.
  1687. * @param param Additional info about the event. Currently this will
  1688. * always be set to NULL.
  1689. */
  1690. void (*on_ice_transport_error)(int index, pj_ice_strans_op op,
  1691. pj_status_t status, void *param);
  1692. /**
  1693. * Callback when the sound device is about to be opened or closed.
  1694. * This callback will be called even when null sound device or no
  1695. * sound device is configured by the application (i.e. the
  1696. * #pjsua_set_null_snd_dev() and #pjsua_set_no_snd_dev() APIs).
  1697. * Application can use the API #pjsua_get_snd_dev() to get the info
  1698. * about which sound device is going to be opened/closed.
  1699. *
  1700. * This callback is mostly useful when the application wants to manage
  1701. * the sound device by itself (i.e. with #pjsua_set_no_snd_dev()),
  1702. * to get notified when it should open or close the sound device.
  1703. *
  1704. * @param operation The value will be set to 0 to signal that sound
  1705. * device is about to be closed, and 1 to be opened.
  1706. *
  1707. * @return The callback must return PJ_SUCCESS at the moment.
  1708. */
  1709. pj_status_t (*on_snd_dev_operation)(int operation);
  1710. /**
  1711. * Notification about media events such as video notifications. This
  1712. * callback will most likely be called from media threads, thus
  1713. * application must not perform heavy processing in this callback.
  1714. * Especially, application must not destroy the call or media in this
  1715. * callback. If application needs to perform more complex tasks to
  1716. * handle the event, it should post the task to another thread.
  1717. *
  1718. * @param call_id The call id.
  1719. * @param med_idx The media stream index.
  1720. * @param event The media event.
  1721. */
  1722. void (*on_call_media_event)(pjsua_call_id call_id,
  1723. unsigned med_idx,
  1724. pjmedia_event *event);
  1725. /**
  1726. * This callback can be used by application to implement custom media
  1727. * transport adapter for the call, or to replace the media transport
  1728. * with something completely new altogether.
  1729. *
  1730. * This callback is called when a new call is created. The library has
  1731. * created a media transport for the call, and it is provided as the
  1732. * \a base_tp argument of this callback. Upon returning, the callback
  1733. * must return an instance of media transport to be used by the call.
  1734. *
  1735. * @param call_id Call ID
  1736. * @param media_idx The media index in the SDP for which this media
  1737. * transport will be used.
  1738. * @param base_tp The media transport which otherwise will be
  1739. * used by the call has this callback not been
  1740. * implemented.
  1741. * @param flags Bitmask from pjsua_create_media_transport_flag.
  1742. *
  1743. * @return The callback must return an instance of media
  1744. * transport to be used by the call.
  1745. */
  1746. pjmedia_transport* (*on_create_media_transport)(pjsua_call_id call_id,
  1747. unsigned media_idx,
  1748. pjmedia_transport *base_tp,
  1749. unsigned flags);
  1750. /**
  1751. * Warning: deprecated and may be removed in future release. Application
  1752. * can set SRTP crypto settings (including keys) and keying methods
  1753. * via pjsua_srtp_opt in pjsua_config and pjsua_acc_config.
  1754. * See also ticket #2100.
  1755. *
  1756. * This callback is called before SRTP media transport is created.
  1757. * Application can modify the SRTP setting \a srtp_opt to specify
  1758. * the cryptos & keys and keying methods which are going to be used.
  1759. * Note that only some fields of pjmedia_srtp_setting can be overriden
  1760. * from this callback, i.e: "crypto_count", "crypto", "keying_count",
  1761. * "keying", and "use" (only for initial INVITE), any modification in
  1762. * other fields will be ignored.
  1763. *
  1764. * @param call_id Call ID
  1765. * @param media_idx The media index in the SDP for which this SRTP
  1766. * media transport will be used.
  1767. * @param srtp_opt The SRTP setting. Application can modify this.
  1768. */
  1769. void (*on_create_media_transport_srtp)(pjsua_call_id call_id,
  1770. unsigned media_idx,
  1771. pjmedia_srtp_setting *srtp_opt);
  1772. /**
  1773. * This callback can be used by application to override the account
  1774. * to be used to handle an incoming message. Initially, the account to
  1775. * be used will be calculated automatically by the library. This initial
  1776. * account will be used if application does not implement this callback,
  1777. * or application sets an invalid account upon returning from this
  1778. * callback.
  1779. *
  1780. * Note that currently the incoming messages requiring account assignment
  1781. * are INVITE, MESSAGE, SUBSCRIBE, and unsolicited NOTIFY. This callback
  1782. * may be called before the callback of the SIP event itself, i.e:
  1783. * incoming call, pager, subscription, or unsolicited-event.
  1784. *
  1785. * @param rdata The incoming message.
  1786. * @param acc_id On input, initial account ID calculated automatically
  1787. * by the library. On output, the account ID prefered
  1788. * by application to handle the incoming message.
  1789. */
  1790. void (*on_acc_find_for_incoming)(const pjsip_rx_data *rdata,
  1791. pjsua_acc_id* acc_id);
  1792. /**
  1793. * Calling #pjsua_init() will initiate an async process to resolve and
  1794. * contact each of the STUN server entries to find which is usable.
  1795. * This callback is called when the process is complete, and can be
  1796. * used by the application to start creating and registering accounts.
  1797. * This way, the accounts can avoid call setup delay caused by pending
  1798. * STUN resolution.
  1799. *
  1800. * See also #pj_stun_resolve_cb.
  1801. */
  1802. pj_stun_resolve_cb on_stun_resolution_complete;
  1803. /**
  1804. * Calling #pjsua_handle_ip_change() may involve different operation. This
  1805. * callback is called to report the progress of each enabled operation.
  1806. *
  1807. * @param op The operation.
  1808. * @param status The status of operation.
  1809. * @param info The info from the operation
  1810. *
  1811. */
  1812. void (*on_ip_change_progress)(pjsua_ip_change_op op,
  1813. pj_status_t status,
  1814. const pjsua_ip_change_op_info *info);
  1815. /**
  1816. * Notification about media events such as video notifications. This
  1817. * callback will most likely be called from media threads, thus
  1818. * application must not perform heavy processing in this callback.
  1819. * If application needs to perform more complex tasks to handle
  1820. * the event, it should post the task to another thread.
  1821. *
  1822. * @param event The media event.
  1823. */
  1824. void (*on_media_event)(pjmedia_event *event);
  1825. /**
  1826. * This callback will be invoked when the library implicitly rejects
  1827. * an incoming call.
  1828. *
  1829. * In addition to being declined explicitly using the
  1830. * #pjsua_call_answer()/#pjsua_call_answer2() method,
  1831. * the library may also automatically reject the incoming call due
  1832. * to different scenarios, e.g:
  1833. * - no available call slot.
  1834. * - no available account to handle the call.
  1835. * - when an incoming INVITE is received with, for instance, a message
  1836. * containing invalid SDP.
  1837. *
  1838. * See also #pjsua_on_rejected_incoming_call_cb.
  1839. */
  1840. pjsua_on_rejected_incoming_call_cb on_rejected_incoming_call;
  1841. } pjsua_callback;
  1842. /**
  1843. * This enumeration specifies the usage of SIP Session Timers extension.
  1844. */
  1845. typedef enum pjsua_sip_timer_use
  1846. {
  1847. /**
  1848. * When this flag is specified, Session Timers will not be used in any
  1849. * session, except it is explicitly required in the remote request.
  1850. */
  1851. PJSUA_SIP_TIMER_INACTIVE,
  1852. /**
  1853. * When this flag is specified, Session Timers will be used in all
  1854. * sessions whenever remote supports and uses it.
  1855. */
  1856. PJSUA_SIP_TIMER_OPTIONAL,
  1857. /**
  1858. * When this flag is specified, Session Timers support will be
  1859. * a requirement for the remote to be able to establish a session.
  1860. */
  1861. PJSUA_SIP_TIMER_REQUIRED,
  1862. /**
  1863. * When this flag is specified, Session Timers will always be used
  1864. * in all sessions, regardless whether remote supports/uses it or not.
  1865. */
  1866. PJSUA_SIP_TIMER_ALWAYS
  1867. } pjsua_sip_timer_use;
  1868. /**
  1869. * This constants controls the use of 100rel extension.
  1870. */
  1871. typedef enum pjsua_100rel_use
  1872. {
  1873. /**
  1874. * Not used. For UAC, support for 100rel will be indicated in Supported
  1875. * header so that peer can opt to use it if it wants to. As UAS, this
  1876. * option will NOT cause 100rel to be used even if UAC indicates that
  1877. * it supports this feature.
  1878. */
  1879. PJSUA_100REL_NOT_USED,
  1880. /**
  1881. * Mandatory. UAC will place 100rel in Require header, and UAS will
  1882. * reject incoming calls unless it has 100rel in Supported header.
  1883. */
  1884. PJSUA_100REL_MANDATORY,
  1885. /**
  1886. * Optional. Similar to PJSUA_100REL_NOT_USED, except that as UAS, this
  1887. * option will cause 100rel to be used if UAC indicates that it supports it.
  1888. */
  1889. PJSUA_100REL_OPTIONAL
  1890. } pjsua_100rel_use;
  1891. /**
  1892. * This structure describes the settings to control the API and
  1893. * user agent behavior, and can be specified when calling #pjsua_init().
  1894. * Before setting the values, application must call #pjsua_config_default()
  1895. * to initialize this structure with the default values.
  1896. */
  1897. typedef struct pjsua_config
  1898. {
  1899. /**
  1900. * Maximum calls to support (default: 4). The value specified here
  1901. * must be smaller than or equal to the compile time maximum settings
  1902. * PJSUA_MAX_CALLS. To increase this limit, the library must be
  1903. * recompiled with new PJSUA_MAX_CALLS value.
  1904. */
  1905. unsigned max_calls;
  1906. /**
  1907. * Number of worker threads. Normally application will want to have at
  1908. * least one worker thread, unless when it wants to poll the library
  1909. * periodically, which in this case the worker thread can be set to
  1910. * zero.
  1911. */
  1912. unsigned thread_cnt;
  1913. /**
  1914. * Number of nameservers. If no name server is configured, the SIP SRV
  1915. * resolution would be disabled, and domain will be resolved with
  1916. * standard pj_gethostbyname() function.
  1917. */
  1918. unsigned nameserver_count;
  1919. /**
  1920. * Array of nameservers to be used by the SIP resolver subsystem.
  1921. * The order of the name server specifies the priority (first name
  1922. * server will be used first, unless it is not reachable).
  1923. */
  1924. pj_str_t nameserver[4];
  1925. /**
  1926. * Force loose-route to be used in all route/proxy URIs (outbound_proxy
  1927. * and account's proxy settings). When this setting is enabled, the
  1928. * library will check all the route/proxy URIs specified in the settings
  1929. * and append ";lr" parameter to the URI if the parameter is not present.
  1930. *
  1931. * Default: 1
  1932. */
  1933. pj_bool_t force_lr;
  1934. /**
  1935. * Number of outbound proxies in the \a outbound_proxy array.
  1936. */
  1937. unsigned outbound_proxy_cnt;
  1938. /**
  1939. * Specify the URL of outbound proxies to visit for all outgoing requests.
  1940. * The outbound proxies will be used for all accounts, and it will
  1941. * be used to build the route set for outgoing requests. The final
  1942. * route set for outgoing requests will consists of the outbound proxies
  1943. * and the proxy configured in the account.
  1944. */
  1945. pj_str_t outbound_proxy[4];
  1946. /**
  1947. * Warning: deprecated, please use \a stun_srv field instead. To maintain
  1948. * backward compatibility, if \a stun_srv_cnt is zero then the value of
  1949. * this field will be copied to \a stun_srv field, if present.
  1950. *
  1951. * Specify domain name to be resolved with DNS SRV resolution to get the
  1952. * address of the STUN server. Alternatively application may specify
  1953. * \a stun_host instead.
  1954. *
  1955. * If DNS SRV resolution failed for this domain, then DNS A resolution
  1956. * will be performed only if \a stun_host is specified.
  1957. */
  1958. pj_str_t stun_domain;
  1959. /**
  1960. * Warning: deprecated, please use \a stun_srv field instead. To maintain
  1961. * backward compatibility, if \a stun_srv_cnt is zero then the value of
  1962. * this field will be copied to \a stun_srv field, if present.
  1963. *
  1964. * Specify STUN server to be used, in "HOST[:PORT]" format. If port is
  1965. * not specified, default port 3478 will be used.
  1966. */
  1967. pj_str_t stun_host;
  1968. /**
  1969. * Number of STUN server entries in \a stun_srv array.
  1970. */
  1971. unsigned stun_srv_cnt;
  1972. /**
  1973. * Array of STUN servers to try. The library will try to resolve and
  1974. * contact each of the STUN server entry until it finds one that is
  1975. * usable. Each entry may be a domain name, host name, IP address, and
  1976. * it may contain an optional port number. For example:
  1977. * - "pjsip.org" (domain name)
  1978. * - "sip.pjsip.org" (host name)
  1979. * - "pjsip.org:33478" (domain name and a non-standard port number)
  1980. * - "10.0.0.1:3478" (IP address and port number)
  1981. *
  1982. * When nameserver is configured in the \a pjsua_config.nameserver field,
  1983. * if entry is not an IP address, it will be resolved with DNS SRV
  1984. * resolution first, and it will fallback to use DNS A resolution if this
  1985. * fails. Port number may be specified even if the entry is a domain name,
  1986. * in case the DNS SRV resolution should fallback to a non-standard port.
  1987. *
  1988. * When nameserver is not configured, entries will be resolved with
  1989. * #pj_gethostbyname() if it's not an IP address. Port number may be
  1990. * specified if the server is not listening in standard STUN port.
  1991. */
  1992. pj_str_t stun_srv[8];
  1993. /**
  1994. * This specifies if the library should try to do an IPv6 resolution of
  1995. * the STUN servers if the IPv4 resolution fails. It can be useful
  1996. * in an IPv6-only environment, including on NAT64.
  1997. *
  1998. * Default: PJ_FALSE
  1999. */
  2000. pj_bool_t stun_try_ipv6;
  2001. /**
  2002. * This specifies if the library should ignore failure with the
  2003. * STUN servers. If this is set to PJ_FALSE, the library will refuse to
  2004. * start if it fails to resolve or contact any of the STUN servers.
  2005. *
  2006. * This setting will also determine what happens if STUN servers are
  2007. * unavailable during runtime (if set to PJ_FALSE, calls will
  2008. * directly fail, otherwise (if PJ_TRUE) call medias will
  2009. * fallback to proceed as though not using STUN servers.
  2010. *
  2011. * Default: PJ_TRUE
  2012. */
  2013. pj_bool_t stun_ignore_failure;
  2014. /**
  2015. * This specifies whether STUN requests for resolving socket mapped
  2016. * address should use the new format, i.e: having STUN magic cookie
  2017. * in its transaction ID.
  2018. *
  2019. * Default: PJ_FALSE
  2020. */
  2021. pj_bool_t stun_map_use_stun2;
  2022. /**
  2023. * Support for adding and parsing NAT type in the SDP to assist
  2024. * troubleshooting. The valid values are:
  2025. * - 0: no information will be added in SDP, and parsing is disabled.
  2026. * - 1: only the NAT type number is added.
  2027. * - 2: add both NAT type number and name.
  2028. *
  2029. * Default: 1
  2030. */
  2031. int nat_type_in_sdp;
  2032. /**
  2033. * Specify how the support for reliable provisional response (100rel/
  2034. * PRACK) should be used by default. Note that this setting can be
  2035. * further customized in account configuration (#pjsua_acc_config).
  2036. *
  2037. * Default: PJSUA_100REL_NOT_USED
  2038. */
  2039. pjsua_100rel_use require_100rel;
  2040. /**
  2041. * Specify the usage of Session Timers for all sessions. See the
  2042. * #pjsua_sip_timer_use for possible values. Note that this setting can be
  2043. * further customized in account configuration (#pjsua_acc_config).
  2044. *
  2045. * Default: PJSUA_SIP_TIMER_OPTIONAL
  2046. */
  2047. pjsua_sip_timer_use use_timer;
  2048. /**
  2049. * Handle unsolicited NOTIFY requests containing message waiting
  2050. * indication (MWI) info. Unsolicited MWI is incoming NOTIFY requests
  2051. * which are not requested by client with SUBSCRIBE request.
  2052. *
  2053. * If this is enabled, the library will respond 200/OK to the NOTIFY
  2054. * request and forward the request to \a on_mwi_info() callback.
  2055. *
  2056. * Note: the callback will not be invoked and 481/"No account to handle" response
  2057. * will be sent if this is enabled but no account is configured.
  2058. *
  2059. * See also \a mwi_enabled field #on pjsua_acc_config.
  2060. *
  2061. * Default: PJ_TRUE
  2062. *
  2063. */
  2064. pj_bool_t enable_unsolicited_mwi;
  2065. /**
  2066. * Specify Session Timer settings, see #pjsip_timer_setting.
  2067. * Note that this setting can be further customized in account
  2068. * configuration (#pjsua_acc_config).
  2069. */
  2070. pjsip_timer_setting timer_setting;
  2071. /**
  2072. * Number of credentials in the credential array.
  2073. */
  2074. unsigned cred_count;
  2075. /**
  2076. * Array of credentials. These credentials will be used by all accounts,
  2077. * and can be used to authenticate against outbound proxies. If the
  2078. * credential is specific to the account, then application should set
  2079. * the credential in the pjsua_acc_config rather than the credential
  2080. * here.
  2081. */
  2082. pjsip_cred_info cred_info[PJSUA_ACC_MAX_PROXIES];
  2083. /**
  2084. * Application callback to receive various event notifications from
  2085. * the library.
  2086. */
  2087. pjsua_callback cb;
  2088. /**
  2089. * Optional user agent string (default empty). If it's empty, no
  2090. * User-Agent header will be sent with outgoing requests.
  2091. */
  2092. pj_str_t user_agent;
  2093. /**
  2094. * Specify default value of secure media transport usage.
  2095. * Valid values are PJMEDIA_SRTP_DISABLED, PJMEDIA_SRTP_OPTIONAL, and
  2096. * PJMEDIA_SRTP_MANDATORY.
  2097. *
  2098. * Note that this setting can be further customized in account
  2099. * configuration (#pjsua_acc_config).
  2100. *
  2101. * Default: #PJSUA_DEFAULT_USE_SRTP
  2102. */
  2103. pjmedia_srtp_use use_srtp;
  2104. /**
  2105. * Specify whether SRTP requires secure signaling to be used. This option
  2106. * is only used when \a use_srtp option above is non-zero.
  2107. *
  2108. * Valid values are:
  2109. * 0: SRTP does not require secure signaling
  2110. * 1: SRTP requires secure transport such as TLS
  2111. * 2: SRTP requires secure end-to-end transport (SIPS)
  2112. *
  2113. * Note that this setting can be further customized in account
  2114. * configuration (#pjsua_acc_config).
  2115. *
  2116. * Default: #PJSUA_DEFAULT_SRTP_SECURE_SIGNALING
  2117. */
  2118. int srtp_secure_signaling;
  2119. /**
  2120. * This setting has been deprecated and will be ignored.
  2121. */
  2122. pj_bool_t srtp_optional_dup_offer;
  2123. /**
  2124. * Specify SRTP transport setting. Application can initialize it with
  2125. * default values using pjsua_srtp_opt_default().
  2126. */
  2127. pjsua_srtp_opt srtp_opt;
  2128. /**
  2129. * Disconnect other call legs when more than one 2xx responses for
  2130. * outgoing INVITE are received due to forking. Currently the library
  2131. * is not able to handle simultaneous forked media, so disconnecting
  2132. * the other call legs is necessary.
  2133. *
  2134. * With this setting enabled, the library will handle only one of the
  2135. * connected call leg, and the other connected call legs will be
  2136. * disconnected.
  2137. *
  2138. * Default: PJ_TRUE (only disable this setting for testing purposes).
  2139. */
  2140. pj_bool_t hangup_forked_call;
  2141. /**
  2142. * Specify whether to enable UPnP.
  2143. *
  2144. * Note that this setting can be further customized in account
  2145. * configuration (#pjsua_acc_config).
  2146. *
  2147. * Default: PJ_FALSE
  2148. */
  2149. pj_bool_t enable_upnp;
  2150. /**
  2151. * Specify which interface to use for UPnP. If empty, UPnP will use
  2152. * the first suitable interface found.
  2153. *
  2154. * Note that this setting is only applicable if UPnP is enabled and
  2155. * the string must be NULL terminated.
  2156. *
  2157. * Default: empty string
  2158. */
  2159. pj_str_t upnp_if_name;
  2160. } pjsua_config;
  2161. /**
  2162. * Flags to be given to pjsua_destroy2()
  2163. */
  2164. typedef enum pjsua_destroy_flag
  2165. {
  2166. /**
  2167. * Allow sending outgoing messages (such as unregistration, event
  2168. * unpublication, BYEs, unsubscription, etc.), but do not wait for
  2169. * responses. This is useful to perform "best effort" clean up
  2170. * without delaying the shutdown process waiting for responses.
  2171. */
  2172. PJSUA_DESTROY_NO_RX_MSG = 1,
  2173. /**
  2174. * If this flag is set, do not send any outgoing messages at all.
  2175. * This flag is useful if application knows that the network which
  2176. * the messages are to be sent on is currently down.
  2177. */
  2178. PJSUA_DESTROY_NO_TX_MSG = 2,
  2179. /**
  2180. * Do not send or receive messages during destroy. This flag is
  2181. * shorthand for PJSUA_DESTROY_NO_RX_MSG + PJSUA_DESTROY_NO_TX_MSG.
  2182. */
  2183. PJSUA_DESTROY_NO_NETWORK = PJSUA_DESTROY_NO_RX_MSG |
  2184. PJSUA_DESTROY_NO_TX_MSG
  2185. } pjsua_destroy_flag;
  2186. /**
  2187. * Use this function to initialize pjsua config.
  2188. *
  2189. * @param cfg pjsua config to be initialized.
  2190. */
  2191. PJ_DECL(void) pjsua_config_default(pjsua_config *cfg);
  2192. /** The implementation has been moved to sip_auth.h */
  2193. #define pjsip_cred_dup pjsip_cred_info_dup
  2194. /**
  2195. * Duplicate pjsua_config.
  2196. *
  2197. * @param pool The pool to get memory from.
  2198. * @param dst Destination config.
  2199. * @param src Source config.
  2200. */
  2201. PJ_DECL(void) pjsua_config_dup(pj_pool_t *pool,
  2202. pjsua_config *dst,
  2203. const pjsua_config *src);
  2204. /**
  2205. * This structure describes additional information to be sent with
  2206. * outgoing SIP message. It can (optionally) be specified for example
  2207. * with #pjsua_call_make_call(), #pjsua_call_answer(), #pjsua_call_hangup(),
  2208. * #pjsua_call_set_hold(), #pjsua_call_send_im(), and many more.
  2209. *
  2210. * Application MUST call #pjsua_msg_data_init() to initialize this
  2211. * structure before setting its values.
  2212. */
  2213. struct pjsua_msg_data
  2214. {
  2215. /**
  2216. * Optional remote target URI (i.e. Target header). If NULL, the target
  2217. * will be set to the remote URI (To header). This field is used by
  2218. * pjsua_call_make_call(), pjsua_im_send(), pjsua_call_reinvite(),
  2219. * pjsua_call_set_hold(), and pjsua_call_update().
  2220. */
  2221. pj_str_t target_uri;
  2222. /**
  2223. * Optional local URI (i.e. From header). If NULL, the account ID
  2224. * \a pjsua_acc_config.id is used for the From header. This field is
  2225. * currently used only by pjsua_call_make_call() and pjsua_im_send().
  2226. */
  2227. pj_str_t local_uri;
  2228. /**
  2229. * Additional message headers as linked list. Application can add
  2230. * headers to the list by creating the header, either from the heap/pool
  2231. * or from temporary local variable, and add the header using
  2232. * linked list operation. See pjsua_app.c for some sample codes.
  2233. */
  2234. pjsip_hdr hdr_list;
  2235. /**
  2236. * MIME type of optional message body.
  2237. */
  2238. pj_str_t content_type;
  2239. /**
  2240. * Optional message body to be added to the message, only when the
  2241. * message doesn't have a body.
  2242. */
  2243. pj_str_t msg_body;
  2244. /**
  2245. * Content type of the multipart body. If application wants to send
  2246. * multipart message bodies, it puts the parts in \a parts and set
  2247. * the content type in \a multipart_ctype. If the message already
  2248. * contains a body, the body will be added to the multipart bodies.
  2249. */
  2250. pjsip_media_type multipart_ctype;
  2251. /**
  2252. * List of multipart parts. If application wants to send multipart
  2253. * message bodies, it puts the parts in \a parts and set the content
  2254. * type in \a multipart_ctype. If the message already contains a body,
  2255. * the body will be added to the multipart bodies.
  2256. */
  2257. pjsip_multipart_part multipart_parts;
  2258. };
  2259. /**
  2260. * Initialize message data.
  2261. *
  2262. * @param msg_data Message data to be initialized.
  2263. */
  2264. PJ_DECL(void) pjsua_msg_data_init(pjsua_msg_data *msg_data);
  2265. /**
  2266. * Clone message data.
  2267. *
  2268. * @param pool Pool to allocate memory for the new message data.
  2269. * @param rhs Message data to be cloned.
  2270. *
  2271. * @return The new message data.
  2272. */
  2273. PJ_DECL(pjsua_msg_data*) pjsua_msg_data_clone(pj_pool_t *pool,
  2274. const pjsua_msg_data *rhs);
  2275. /**
  2276. * Instantiate pjsua application. Application must call this function before
  2277. * calling any other functions, to make sure that the underlying libraries
  2278. * are properly initialized. Once this function has returned success,
  2279. * application must call pjsua_destroy() before quitting.
  2280. *
  2281. * @return PJ_SUCCESS on success, or the appropriate error code.
  2282. */
  2283. PJ_DECL(pj_status_t) pjsua_create(void);
  2284. /** Forward declaration */
  2285. typedef struct pjsua_media_config pjsua_media_config;
  2286. /**
  2287. * Initialize pjsua with the specified settings. All the settings are
  2288. * optional, and the default values will be used when the config is not
  2289. * specified.
  2290. *
  2291. * Note that #pjsua_create() MUST be called before calling this function.
  2292. *
  2293. * @param ua_cfg User agent configuration.
  2294. * @param log_cfg Optional logging configuration.
  2295. * @param media_cfg Optional media configuration.
  2296. *
  2297. * @return PJ_SUCCESS on success, or the appropriate error code.
  2298. */
  2299. PJ_DECL(pj_status_t) pjsua_init(const pjsua_config *ua_cfg,
  2300. const pjsua_logging_config *log_cfg,
  2301. const pjsua_media_config *media_cfg);
  2302. /**
  2303. * Application is recommended to call this function after all initialization
  2304. * is done, so that the library can do additional checking set up
  2305. * additional
  2306. *
  2307. * Application may call this function anytime after #pjsua_init().
  2308. *
  2309. * @return PJ_SUCCESS on success, or the appropriate error code.
  2310. */
  2311. PJ_DECL(pj_status_t) pjsua_start(void);
  2312. /**
  2313. * Destroy pjsua. Application is recommended to perform graceful shutdown
  2314. * before calling this function (such as unregister the account from the SIP
  2315. * server, terminate presense subscription, and hangup active calls), however,
  2316. * this function will do all of these if it finds there are active sessions
  2317. * that need to be terminated. This function will approximately block for
  2318. * one second to wait for replies from remote.
  2319. *
  2320. * Application.may safely call this function more than once if it doesn't
  2321. * keep track of it's state.
  2322. *
  2323. * @see pjsua_destroy2()
  2324. *
  2325. * @return PJ_SUCCESS on success, or the appropriate error code.
  2326. */
  2327. PJ_DECL(pj_status_t) pjsua_destroy(void);
  2328. /**
  2329. * Retrieve pjsua state.
  2330. *
  2331. * @return pjsua state.
  2332. */
  2333. PJ_DECL(pjsua_state) pjsua_get_state(void);
  2334. /**
  2335. * Variant of destroy with additional flags.
  2336. *
  2337. * @param flags Combination of pjsua_destroy_flag enumeration.
  2338. *
  2339. * @return PJ_SUCCESS on success, or the appropriate error code.
  2340. */
  2341. PJ_DECL(pj_status_t) pjsua_destroy2(unsigned flags);
  2342. /**
  2343. * Poll pjsua for events, and if necessary block the caller thread for
  2344. * the specified maximum interval (in miliseconds).
  2345. *
  2346. * Application doesn't normally need to call this function if it has
  2347. * configured worker thread (\a thread_cnt field) in pjsua_config structure,
  2348. * because polling then will be done by these worker threads instead.
  2349. *
  2350. * @param msec_timeout Maximum time to wait, in miliseconds.
  2351. *
  2352. * @return The number of events that have been handled during the
  2353. * poll. Negative value indicates error, and application
  2354. * can retrieve the error as (status = -return_value).
  2355. */
  2356. PJ_DECL(int) pjsua_handle_events(unsigned msec_timeout);
  2357. /**
  2358. * Signal all worker threads to quit. This will only wait until internal
  2359. * threads are done.
  2360. */
  2361. PJ_DECL(void) pjsua_stop_worker_threads(void);
  2362. /**
  2363. * Create memory pool to be used by the application. Once application
  2364. * finished using the pool, it must be released with pj_pool_release().
  2365. *
  2366. * @param name Optional pool name.
  2367. * @param init_size Initial size of the pool.
  2368. * @param increment Increment size.
  2369. *
  2370. * @return The pool, or NULL when there's no memory.
  2371. */
  2372. PJ_DECL(pj_pool_t*) pjsua_pool_create(const char *name, pj_size_t init_size,
  2373. pj_size_t increment);
  2374. /**
  2375. * Application can call this function at any time (after pjsua_create(), of
  2376. * course) to change logging settings.
  2377. *
  2378. * @param c Logging configuration.
  2379. *
  2380. * @return PJ_SUCCESS on success, or the appropriate error code.
  2381. */
  2382. PJ_DECL(pj_status_t) pjsua_reconfigure_logging(const pjsua_logging_config *c);
  2383. /**
  2384. * Internal function to get SIP endpoint instance of pjsua, which is
  2385. * needed for example to register module, create transports, etc.
  2386. * Only valid after #pjsua_init() is called.
  2387. *
  2388. * @return SIP endpoint instance.
  2389. */
  2390. PJ_DECL(pjsip_endpoint*) pjsua_get_pjsip_endpt(void);
  2391. /**
  2392. * Internal function to get media endpoint instance.
  2393. * Only valid after #pjsua_init() is called.
  2394. *
  2395. * @return Media endpoint instance.
  2396. */
  2397. PJ_DECL(pjmedia_endpt*) pjsua_get_pjmedia_endpt(void);
  2398. /**
  2399. * Internal function to get PJSUA pool factory.
  2400. * Only valid after #pjsua_create() is called.
  2401. *
  2402. * @return Pool factory currently used by PJSUA.
  2403. */
  2404. PJ_DECL(pj_pool_factory*) pjsua_get_pool_factory(void);
  2405. /*****************************************************************************
  2406. * Utilities.
  2407. *
  2408. */
  2409. /**
  2410. * This structure is used to represent the result of the STUN server
  2411. * resolution and testing, the #pjsua_resolve_stun_servers() function.
  2412. * This structure will be passed in #pj_stun_resolve_cb callback.
  2413. */
  2414. struct pj_stun_resolve_result
  2415. {
  2416. /**
  2417. * Arbitrary data that was passed to #pjsua_resolve_stun_servers()
  2418. * function.
  2419. */
  2420. void *token;
  2421. /**
  2422. * This will contain PJ_SUCCESS if at least one usable STUN server
  2423. * is found, otherwise it will contain the last error code during
  2424. * the operation.
  2425. */
  2426. pj_status_t status;
  2427. /**
  2428. * The server name that yields successful result. This will only
  2429. * contain value if status is successful.
  2430. */
  2431. pj_str_t name;
  2432. /**
  2433. * The server IP address. This will only contain value if status
  2434. * is successful.
  2435. */
  2436. pj_sockaddr addr;
  2437. /**
  2438. * The index of the usable STUN server.
  2439. */
  2440. unsigned index;
  2441. };
  2442. /**
  2443. * This structure describe the parameter passed to #pjsua_handle_ip_change().
  2444. */
  2445. typedef struct pjsua_ip_change_param
  2446. {
  2447. /**
  2448. * If set to PJ_TRUE, this will restart the transport listener.
  2449. * Note that if restarting listener is enabled and the listener is
  2450. * configured with a bound address, the address will be reset
  2451. * so it will bind to any address (e.g: IPv4 "0.0.0.0" or IPv6 "::").
  2452. *
  2453. * Default : PJ_TRUE
  2454. */
  2455. pj_bool_t restart_listener;
  2456. /**
  2457. * If \a restart listener is set to PJ_TRUE, some delay might be needed
  2458. * for the listener to be restarted. Use this to set the delay.
  2459. *
  2460. * Default : PJSUA_TRANSPORT_RESTART_DELAY_TIME
  2461. */
  2462. unsigned restart_lis_delay;
  2463. /**
  2464. * If set to PJ_TRUE, this will forcefully shutdown all transports.
  2465. * Note that this will shutdown TCP/TLS transports only, UDP transport
  2466. * should be restarted via restart_listener.
  2467. *
  2468. * Default : PJ_TRUE
  2469. */
  2470. pj_bool_t shutdown_transport;
  2471. } pjsua_ip_change_param;
  2472. /**
  2473. * This structure describe the account config specific to IP address change.
  2474. */
  2475. typedef struct pjsua_ip_change_acc_cfg
  2476. {
  2477. /**
  2478. * Shutdown the transport used for account registration. If this is set to
  2479. * PJ_TRUE, the transport will be shutdown altough it's used by multiple
  2480. * account. Shutdown transport will be followed by re-Registration if
  2481. * pjsua_acc_config.allow_contact_rewrite is enabled.
  2482. *
  2483. * Default: PJ_TRUE
  2484. */
  2485. pj_bool_t shutdown_tp;
  2486. /**
  2487. * Hangup active calls associated with the account. If this is set to
  2488. * PJ_TRUE, then the calls will be hang up.
  2489. *
  2490. * Default: PJ_FALSE
  2491. */
  2492. pj_bool_t hangup_calls;
  2493. /**
  2494. * Specify the call flags used in the re-INVITE when \a hangup_calls is set
  2495. * to PJ_FALSE. If this is set to 0, no re-INVITE will be sent. The
  2496. * re-INVITE will be sent after re-Registration is finished.
  2497. *
  2498. * Default: PJSUA_CALL_REINIT_MEDIA | PJSUA_CALL_UPDATE_CONTACT |
  2499. * PJSUA_CALL_UPDATE_VIA
  2500. */
  2501. unsigned reinvite_flags;
  2502. /**
  2503. * For refreshing the call, use SIP UPDATE, instead of re-INVITE, if
  2504. * remote supports it (by publishing it in Allow header). If remote
  2505. * does not support UPDATE method or somehow the UPDATE attempt fails,
  2506. * it will fallback to using re-INVITE. The \a reinvite_flags will be
  2507. * used regardless whether it is re-INVITE or UPDATE that is sent.
  2508. *
  2509. * Default: PJ_FALSE (using re-INVITE).
  2510. */
  2511. pj_bool_t reinv_use_update;
  2512. } pjsua_ip_change_acc_cfg;
  2513. /**
  2514. * Call this function to initialize \a pjsua_ip_change_param with default
  2515. * values.
  2516. *
  2517. * @param param The IP change param to be initialized.
  2518. */
  2519. PJ_DECL(void) pjsua_ip_change_param_default(pjsua_ip_change_param *param);
  2520. /**
  2521. * This is a utility function to detect NAT type in front of this
  2522. * endpoint. Once invoked successfully, this function will complete
  2523. * asynchronously and report the result in \a on_nat_detect() callback
  2524. * of pjsua_callback.
  2525. *
  2526. * After NAT has been detected and the callback is called, application can
  2527. * get the detected NAT type by calling #pjsua_get_nat_type(). Application
  2528. * can also perform NAT detection by calling #pjsua_detect_nat_type()
  2529. * again at later time.
  2530. *
  2531. * Note that STUN must be enabled to run this function successfully.
  2532. *
  2533. * @return PJ_SUCCESS on success, or the appropriate error code.
  2534. */
  2535. PJ_DECL(pj_status_t) pjsua_detect_nat_type(void);
  2536. /**
  2537. * Get the NAT type as detected by #pjsua_detect_nat_type() function.
  2538. * This function will only return useful NAT type after #pjsua_detect_nat_type()
  2539. * has completed successfully and \a on_nat_detect() callback has been called.
  2540. *
  2541. * @param type NAT type.
  2542. *
  2543. * @return When detection is in progress, this function will
  2544. * return PJ_EPENDING and \a type will be set to
  2545. * PJ_STUN_NAT_TYPE_UNKNOWN. After NAT type has been
  2546. * detected successfully, this function will return
  2547. * PJ_SUCCESS and \a type will be set to the correct
  2548. * value. Other return values indicate error and
  2549. * \a type will be set to PJ_STUN_NAT_TYPE_ERR_UNKNOWN.
  2550. *
  2551. * @see pjsua_call_get_rem_nat_type()
  2552. */
  2553. PJ_DECL(pj_status_t) pjsua_get_nat_type(pj_stun_nat_type *type);
  2554. /**
  2555. * Update the STUN servers list. The #pjsua_init() must have been called
  2556. * before calling this function.
  2557. *
  2558. * @param count Number of STUN server entries.
  2559. * @param srv Array of STUN server entries to try. Please see
  2560. * the \a stun_srv field in the #pjsua_config
  2561. * documentation about the format of this entry.
  2562. * @param wait Specify non-zero to make the function block until
  2563. * it gets the result. In this case, the function
  2564. * will block while the resolution is being done,
  2565. * and the callback will be called before this function
  2566. * returns.
  2567. *
  2568. * @return If \a wait parameter is non-zero, this will return
  2569. * PJ_SUCCESS if one usable STUN server is found.
  2570. * Otherwise it will always return PJ_SUCCESS, and
  2571. * application will be notified about the result in
  2572. * the callback on_stun_resolution_complete().
  2573. */
  2574. PJ_DECL(pj_status_t) pjsua_update_stun_servers(unsigned count, pj_str_t srv[],
  2575. pj_bool_t wait);
  2576. /**
  2577. * Auxiliary function to resolve and contact each of the STUN server
  2578. * entries (sequentially) to find which is usable. The #pjsua_init() must
  2579. * have been called before calling this function.
  2580. *
  2581. * @param count Number of STUN server entries to try.
  2582. * @param srv Array of STUN server entries to try. Please see
  2583. * the \a stun_srv field in the #pjsua_config
  2584. * documentation about the format of this entry.
  2585. * @param wait Specify non-zero to make the function block until
  2586. * it gets the result. In this case, the function
  2587. * will block while the resolution is being done,
  2588. * and the callback will be called before this function
  2589. * returns.
  2590. * @param token Arbitrary token to be passed back to application
  2591. * in the callback.
  2592. * @param cb Callback to be called to notify the result of
  2593. * the function.
  2594. *
  2595. * @return If \a wait parameter is non-zero, this will return
  2596. * PJ_SUCCESS if one usable STUN server is found.
  2597. * Otherwise it will always return PJ_SUCCESS, and
  2598. * application will be notified about the result in
  2599. * the callback.
  2600. */
  2601. PJ_DECL(pj_status_t) pjsua_resolve_stun_servers(unsigned count,
  2602. pj_str_t srv[],
  2603. pj_bool_t wait,
  2604. void *token,
  2605. pj_stun_resolve_cb cb);
  2606. /**
  2607. * Cancel pending STUN resolution which match the specified token.
  2608. *
  2609. * @param token The token to match. This token was given to
  2610. * #pjsua_resolve_stun_servers()
  2611. * @param notify_cb Boolean to control whether the callback should
  2612. * be called for cancelled resolutions. When the
  2613. * callback is called, the status in the result
  2614. * will be set as PJ_ECANCELLED.
  2615. *
  2616. * @return PJ_SUCCESS if there is at least one pending STUN
  2617. * resolution cancelled, or PJ_ENOTFOUND if there is
  2618. * no matching one, or other error.
  2619. */
  2620. PJ_DECL(pj_status_t) pjsua_cancel_stun_resolution(void *token,
  2621. pj_bool_t notify_cb);
  2622. /**
  2623. * This is a utility function to verify that valid SIP url is given. If the
  2624. * URL is a valid SIP/SIPS scheme, PJ_SUCCESS will be returned.
  2625. *
  2626. * @param url The URL, as NULL terminated string.
  2627. *
  2628. * @return PJ_SUCCESS on success, or the appropriate error code.
  2629. *
  2630. * @see pjsua_verify_url()
  2631. */
  2632. PJ_DECL(pj_status_t) pjsua_verify_sip_url(const char *url);
  2633. /**
  2634. * This is a utility function to verify that valid URI is given. Unlike
  2635. * pjsua_verify_sip_url(), this function will return PJ_SUCCESS if tel: URI
  2636. * is given.
  2637. *
  2638. * @param url The URL, as NULL terminated string.
  2639. *
  2640. * @return PJ_SUCCESS on success, or the appropriate error code.
  2641. *
  2642. * @see pjsua_verify_sip_url()
  2643. */
  2644. PJ_DECL(pj_status_t) pjsua_verify_url(const char *url);
  2645. /**
  2646. * Schedule a timer entry. Note that the timer callback may be executed
  2647. * by different thread, depending on whether worker thread is enabled or
  2648. * not.
  2649. *
  2650. * @param entry Timer heap entry.
  2651. * @param delay The interval to expire.
  2652. *
  2653. * @return PJ_SUCCESS on success, or the appropriate error code.
  2654. *
  2655. * @see pjsip_endpt_schedule_timer()
  2656. */
  2657. #if PJ_TIMER_DEBUG
  2658. #define pjsua_schedule_timer(e,d) pjsua_schedule_timer_dbg(e,d,\
  2659. __FILE__,__LINE__)
  2660. PJ_DECL(pj_status_t) pjsua_schedule_timer_dbg(pj_timer_entry *entry,
  2661. const pj_time_val *delay,
  2662. const char *src_file,
  2663. int src_line);
  2664. #else
  2665. PJ_DECL(pj_status_t) pjsua_schedule_timer(pj_timer_entry *entry,
  2666. const pj_time_val *delay);
  2667. #endif
  2668. /**
  2669. * Schedule a callback function to be called after a specified time interval.
  2670. * Note that the callback may be executed by different thread, depending on
  2671. * whether worker thread is enabled or not.
  2672. *
  2673. * @param cb The callback function.
  2674. * @param user_data The user data.
  2675. * @param msec_delay The time interval in msec.
  2676. *
  2677. * @return PJ_SUCCESS on success, or the appropriate error code.
  2678. */
  2679. #if PJ_TIMER_DEBUG
  2680. #define pjsua_schedule_timer2(cb,u,d) \
  2681. pjsua_schedule_timer2_dbg(cb,u,d,__FILE__,__LINE__)
  2682. PJ_DECL(pj_status_t) pjsua_schedule_timer2_dbg(void (*cb)(void *user_data),
  2683. void *user_data,
  2684. unsigned msec_delay,
  2685. const char *src_file,
  2686. int src_line);
  2687. #else
  2688. PJ_DECL(pj_status_t) pjsua_schedule_timer2(void (*cb)(void *user_data),
  2689. void *user_data,
  2690. unsigned msec_delay);
  2691. #endif
  2692. /**
  2693. * Cancel the previously scheduled timer.
  2694. *
  2695. * @param entry Timer heap entry.
  2696. *
  2697. * @see pjsip_endpt_cancel_timer()
  2698. */
  2699. PJ_DECL(void) pjsua_cancel_timer(pj_timer_entry *entry);
  2700. /**
  2701. * This is a utility function to display error message for the specified
  2702. * error code. The error message will be sent to the log.
  2703. *
  2704. * @param sender The log sender field.
  2705. * @param title Message title for the error.
  2706. * @param status Status code.
  2707. */
  2708. PJ_DECL(void) pjsua_perror(const char *sender, const char *title,
  2709. pj_status_t status);
  2710. /**
  2711. * This is a utility function to dump the stack states to log, using
  2712. * verbosity level 3.
  2713. *
  2714. * @param detail Will print detailed output (such as list of
  2715. * SIP transactions) when non-zero.
  2716. */
  2717. PJ_DECL(void) pjsua_dump(pj_bool_t detail);
  2718. /**
  2719. * Inform the stack that IP address change event was detected.
  2720. * The stack will:
  2721. * 1. Restart the listener (this step is configurable via
  2722. * \a pjsua_ip_change_param.restart_listener).
  2723. * 2. Shutdown the transport used by account registration (this step is
  2724. * configurable via \a pjsua_acc_config.ip_change_cfg.shutdown_tp).
  2725. * 3. Update contact URI by sending re-Registration (this step is configurable
  2726. * via a\ pjsua_acc_config.allow_contact_rewrite and
  2727. * a\ pjsua_acc_config.contact_rewrite_method)
  2728. * 4. Hangup active calls (this step is configurable via
  2729. * a\ pjsua_acc_config.ip_change_cfg.hangup_calls) or
  2730. * continue the call by sending re-INVITE
  2731. * (configurable via \a pjsua_acc_config.ip_change_cfg.reinvite_flags).
  2732. *
  2733. * @param param The IP change parameter, have a look at
  2734. * #pjsua_ip_change_param.
  2735. *
  2736. * @return PJ_SUCCESS on success, other on error.
  2737. */
  2738. PJ_DECL(pj_status_t) pjsua_handle_ip_change(
  2739. const pjsua_ip_change_param *param);
  2740. /**
  2741. * @}
  2742. */
  2743. /*****************************************************************************
  2744. * TRANSPORT API
  2745. */
  2746. /**
  2747. * @defgroup PJSUA_LIB_TRANSPORT PJSUA-API Signaling Transport
  2748. * @ingroup PJSUA_LIB
  2749. * @brief API for managing SIP transports
  2750. * @{
  2751. *
  2752. * PJSUA-API supports creating multiple transport instances, for example UDP,
  2753. * TCP, and TLS transport. SIP transport must be created before adding an
  2754. * account.
  2755. */
  2756. /** SIP transport identification.
  2757. */
  2758. typedef int pjsua_transport_id;
  2759. /**
  2760. * Transport configuration for creating transports for both SIP
  2761. * and media. Before setting some values to this structure, application
  2762. * MUST call #pjsua_transport_config_default() to initialize its
  2763. * values with default settings.
  2764. */
  2765. typedef struct pjsua_transport_config
  2766. {
  2767. /**
  2768. * UDP port number to bind locally. This setting MUST be specified
  2769. * even when default port is desired. If the value is zero, the
  2770. * transport will be bound to any available port, and application
  2771. * can query the port by querying the transport info.
  2772. */
  2773. unsigned port;
  2774. /**
  2775. * Specify the port range for socket binding, relative to the start
  2776. * port number specified in \a port. Note that this setting is only
  2777. * applicable to media transport when the start port number is non zero.
  2778. * Media transport is configurable via account setting,
  2779. * i.e: pjsua_acc_config.rtp_cfg, please check the media transport
  2780. * config docs for more info.
  2781. *
  2782. * Available ports are in the range of [\a port, \a port + \a port_range].
  2783. *
  2784. * Default value is zero.
  2785. */
  2786. unsigned port_range;
  2787. /**
  2788. * Specify whether to randomly pick the starting port number from
  2789. * the range of [\a port, \a port + \a port_range]. This setting is
  2790. * used only if both port and port_range are non-zero, and only
  2791. * applicable for the port selection of UDP and loop media transport.
  2792. *
  2793. * Default is PJ_FALSE.
  2794. */
  2795. pj_bool_t randomize_port;
  2796. /**
  2797. * Optional address to advertise as the address of this transport.
  2798. * Application can specify any address or hostname for this field,
  2799. * for example it can point to one of the interface address in the
  2800. * system, or it can point to the public address of a NAT router
  2801. * where port mappings have been configured for the application.
  2802. *
  2803. * Note: this option can be used for both UDP and TCP as well!
  2804. */
  2805. pj_str_t public_addr;
  2806. /**
  2807. * Optional address where the socket should be bound to. This option
  2808. * SHOULD only be used to selectively bind the socket to particular
  2809. * interface (instead of 0.0.0.0), and SHOULD NOT be used to set the
  2810. * published address of a transport (the public_addr field should be
  2811. * used for that purpose).
  2812. *
  2813. * Note that unlike public_addr field, the address (or hostname) here
  2814. * MUST correspond to the actual interface address in the host, since
  2815. * this address will be specified as bind() argument.
  2816. */
  2817. pj_str_t bound_addr;
  2818. /**
  2819. * This specifies TLS settings for TLS transport.
  2820. * It’s only used when creating a SIP TLS transport.
  2821. */
  2822. pjsip_tls_setting tls_setting;
  2823. /**
  2824. * QoS traffic type to be set on this transport. When application wants
  2825. * to apply QoS tagging to the transport, it's preferable to set this
  2826. * field rather than \a qos_param fields since this is more portable.
  2827. *
  2828. * For TLS transport, this field will be ignored, the QoS traffic type
  2829. * can be set via tls_setting.
  2830. *
  2831. * Default is QoS not set.
  2832. */
  2833. pj_qos_type qos_type;
  2834. /**
  2835. * Set the low level QoS parameters to the transport. This is a lower
  2836. * level operation than setting the \a qos_type field and may not be
  2837. * supported on all platforms.
  2838. *
  2839. * For TLS transport, this field will be ignored, the low level QoS
  2840. * parameters can be set via tls_setting.
  2841. *
  2842. * Default is QoS not set.
  2843. */
  2844. pj_qos_params qos_params;
  2845. /**
  2846. * Specify options to be set on the transport.
  2847. *
  2848. * For TLS transport, this field will be ignored, the socket options
  2849. * can be set via tls_setting.
  2850. *
  2851. * By default there is no options.
  2852. *
  2853. */
  2854. pj_sockopt_params sockopt_params;
  2855. } pjsua_transport_config;
  2856. /**
  2857. * Call this function to initialize UDP config with default values.
  2858. *
  2859. * @param cfg The UDP config to be initialized.
  2860. */
  2861. PJ_DECL(void) pjsua_transport_config_default(pjsua_transport_config *cfg);
  2862. /**
  2863. * Duplicate transport config.
  2864. *
  2865. * @param pool The pool.
  2866. * @param dst The destination config.
  2867. * @param src The source config.
  2868. */
  2869. PJ_DECL(void) pjsua_transport_config_dup(pj_pool_t *pool,
  2870. pjsua_transport_config *dst,
  2871. const pjsua_transport_config *src);
  2872. /**
  2873. * This structure describes transport information returned by
  2874. * #pjsua_transport_get_info() function.
  2875. */
  2876. typedef struct pjsua_transport_info
  2877. {
  2878. /**
  2879. * PJSUA transport identification.
  2880. */
  2881. pjsua_transport_id id;
  2882. /**
  2883. * Transport type.
  2884. */
  2885. pjsip_transport_type_e type;
  2886. /**
  2887. * Transport type name.
  2888. */
  2889. pj_str_t type_name;
  2890. /**
  2891. * Transport string info/description.
  2892. */
  2893. pj_str_t info;
  2894. /**
  2895. * Transport flag (see ##pjsip_transport_flags_e).
  2896. */
  2897. unsigned flag;
  2898. /**
  2899. * Local address length.
  2900. */
  2901. unsigned addr_len;
  2902. /**
  2903. * Local/bound address.
  2904. */
  2905. pj_sockaddr local_addr;
  2906. /**
  2907. * Published address (or transport address name).
  2908. */
  2909. pjsip_host_port local_name;
  2910. /**
  2911. * Current number of objects currently referencing this transport.
  2912. */
  2913. unsigned usage_count;
  2914. } pjsua_transport_info;
  2915. /**
  2916. * Create and start a new SIP transport according to the specified
  2917. * settings.
  2918. *
  2919. * @param type Transport type.
  2920. * @param cfg Transport configuration.
  2921. * @param p_id Optional pointer to receive transport ID.
  2922. *
  2923. * @return PJ_SUCCESS on success, or the appropriate error code.
  2924. */
  2925. PJ_DECL(pj_status_t) pjsua_transport_create(pjsip_transport_type_e type,
  2926. const pjsua_transport_config *cfg,
  2927. pjsua_transport_id *p_id);
  2928. /**
  2929. * Register transport that has been created by application. This function
  2930. * is useful if application wants to implement custom SIP transport and use
  2931. * it with pjsua.
  2932. *
  2933. * @param tp Transport instance.
  2934. * @param p_id Optional pointer to receive transport ID.
  2935. *
  2936. * @return PJ_SUCCESS on success, or the appropriate error code.
  2937. */
  2938. PJ_DECL(pj_status_t) pjsua_transport_register(pjsip_transport *tp,
  2939. pjsua_transport_id *p_id);
  2940. /**
  2941. * Register transport factory that has been created by application.
  2942. * This function is useful if application wants to implement custom SIP
  2943. * transport and use it with pjsua.
  2944. *
  2945. * @param tf Transport factory instance.
  2946. * @param p_id Optional pointer to receive transport ID.
  2947. *
  2948. * @return PJ_SUCCESS on success, or the appropriate error code.
  2949. */
  2950. PJ_DECL(pj_status_t) pjsua_tpfactory_register( pjsip_tpfactory *tf,
  2951. pjsua_transport_id *p_id);
  2952. /**
  2953. * Enumerate all transports currently created in the system. This function
  2954. * will return all transport IDs, and application may then call
  2955. * #pjsua_transport_get_info() function to retrieve detailed information
  2956. * about the transport.
  2957. *
  2958. * @param id Array to receive transport ids.
  2959. * @param count In input, specifies the maximum number of elements.
  2960. * On return, it contains the actual number of elements.
  2961. *
  2962. * @return PJ_SUCCESS on success, or the appropriate error code.
  2963. */
  2964. PJ_DECL(pj_status_t) pjsua_enum_transports( pjsua_transport_id id[],
  2965. unsigned *count );
  2966. /**
  2967. * Get information about transports.
  2968. *
  2969. * @param id Transport ID.
  2970. * @param info Pointer to receive transport info.
  2971. *
  2972. * @return PJ_SUCCESS on success, or the appropriate error code.
  2973. */
  2974. PJ_DECL(pj_status_t) pjsua_transport_get_info(pjsua_transport_id id,
  2975. pjsua_transport_info *info);
  2976. #if 0
  2977. // Not implemented.
  2978. /**
  2979. * Disable a transport or re-enable it. By default transport is always
  2980. * enabled after it is created. Disabling a transport does not necessarily
  2981. * close the socket, it will only discard incoming messages and prevent
  2982. * the transport from being used to send outgoing messages.
  2983. *
  2984. * @param id Transport ID.
  2985. * @param enabled Non-zero to enable, zero to disable.
  2986. *
  2987. * @return PJ_SUCCESS on success, or the appropriate error code.
  2988. */
  2989. PJ_DECL(pj_status_t) pjsua_transport_set_enable(pjsua_transport_id id,
  2990. pj_bool_t enabled);
  2991. #endif
  2992. /**
  2993. * Close the transport. The system will wait until all transactions are
  2994. * closed while preventing new users from using the transport, and will
  2995. * close the transport when it is safe to do so.
  2996. *
  2997. * NOTE: Forcefully closing transport (force = PJ_TRUE) is deprecated,
  2998. * since any pending transactions that are using the transport may not
  2999. * terminate properly and can even crash. Application wishing to immediately
  3000. * close the transport for the purpose of restarting it should use
  3001. * #pjsua_handle_ip_change() instead.
  3002. *
  3003. * @param id Transport ID.
  3004. * @param force Must be PJ_FALSE. force = PJ_TRUE is deprecated.
  3005. *
  3006. * @return PJ_SUCCESS on success, or the appropriate error code.
  3007. */
  3008. PJ_DECL(pj_status_t) pjsua_transport_close( pjsua_transport_id id,
  3009. pj_bool_t force );
  3010. /**
  3011. * Start the listener of the transport. This is useful when listener is not
  3012. * automatically started when creating the transport.
  3013. *
  3014. * @param id Transport ID.
  3015. * @param cfg The new transport config used by the listener.
  3016. * Only port, public_addr and bound_addr are used at the
  3017. * moment.
  3018. *
  3019. * @return PJ_SUCCESS on success, or the appropriate error code.
  3020. */
  3021. PJ_DECL(pj_status_t) pjsua_transport_lis_start( pjsua_transport_id id,
  3022. const pjsua_transport_config *cfg);
  3023. /**
  3024. * @}
  3025. */
  3026. /*****************************************************************************
  3027. * ACCOUNT API
  3028. */
  3029. /**
  3030. * @defgroup PJSUA_LIB_ACC PJSUA-API Accounts Management
  3031. * @ingroup PJSUA_LIB
  3032. * @brief PJSUA Accounts management
  3033. * @{
  3034. *
  3035. * PJSUA accounts provide identity (or identities) of the user who is currently
  3036. * using the application. In SIP terms, the identity is used as the <b>From</b>
  3037. * header in outgoing requests.
  3038. *
  3039. * PJSUA-API supports creating and managing multiple accounts. The maximum
  3040. * number of accounts is limited by a compile time constant
  3041. * <tt>PJSUA_MAX_ACC</tt>.
  3042. *
  3043. * Account may or may not have client registration associated with it.
  3044. * An account is also associated with <b>route set</b> and some <b>authentication
  3045. * credentials</b>, which are used when sending SIP request messages using the
  3046. * account. An account also has presence's <b>online status</b>, which
  3047. * will be reported to remote peer when they subscribe to the account's
  3048. * presence, or which is published to a presence server if presence
  3049. * publication is enabled for the account.
  3050. *
  3051. * At least one account MUST be created in the application. If no user
  3052. * association is required, application can create a userless account by
  3053. * calling #pjsua_acc_add_local(). A userless account identifies local endpoint
  3054. * instead of a particular user, and it correspond with a particular
  3055. * transport instance.
  3056. *
  3057. * Also one account must be set as the <b>default account</b>, which is used as
  3058. * the account to use when PJSUA fails to match a request with any other
  3059. * accounts.
  3060. *
  3061. * When sending outgoing SIP requests (such as making calls or sending
  3062. * instant messages), normally PJSUA requires the application to specify
  3063. * which account to use for the request. If no account is specified,
  3064. * PJSUA may be able to select the account by matching the destination
  3065. * domain name, and fall back to default account when no match is found.
  3066. */
  3067. /**
  3068. * Maximum accounts.
  3069. */
  3070. #ifndef PJSUA_MAX_ACC
  3071. # define PJSUA_MAX_ACC 8
  3072. #endif
  3073. /**
  3074. * Default registration interval.
  3075. */
  3076. #ifndef PJSUA_REG_INTERVAL
  3077. # define PJSUA_REG_INTERVAL 300
  3078. #endif
  3079. /**
  3080. * Default maximum time to wait for account unregistration transactions to
  3081. * complete during library shutdown sequence.
  3082. *
  3083. * Default: 4000 (4 seconds)
  3084. */
  3085. #ifndef PJSUA_UNREG_TIMEOUT
  3086. # define PJSUA_UNREG_TIMEOUT 4000
  3087. #endif
  3088. /**
  3089. * Default PUBLISH expiration
  3090. */
  3091. #ifndef PJSUA_PUBLISH_EXPIRATION
  3092. # define PJSUA_PUBLISH_EXPIRATION PJSIP_PUBC_EXPIRATION_NOT_SPECIFIED
  3093. #endif
  3094. /**
  3095. * Default account priority.
  3096. */
  3097. #ifndef PJSUA_DEFAULT_ACC_PRIORITY
  3098. # define PJSUA_DEFAULT_ACC_PRIORITY 0
  3099. #endif
  3100. /**
  3101. * Maximum time to wait for unpublication transaction(s) to complete
  3102. * during shutdown process, before sending unregistration. The library
  3103. * tries to wait for the unpublication (un-PUBLISH) to complete before
  3104. * sending REGISTER request to unregister the account, during library
  3105. * shutdown process. If the value is set too short, it is possible that
  3106. * the unregistration is sent before unpublication completes, causing
  3107. * unpublication request to fail.
  3108. *
  3109. * Default: 2000 (2 seconds)
  3110. */
  3111. #ifndef PJSUA_UNPUBLISH_MAX_WAIT_TIME_MSEC
  3112. # define PJSUA_UNPUBLISH_MAX_WAIT_TIME_MSEC 2000
  3113. #endif
  3114. /**
  3115. * Default auto retry re-registration interval, in seconds. Set to 0
  3116. * to disable this. Application can set the timer on per account basis
  3117. * by setting the pjsua_acc_config.reg_retry_interval field instead.
  3118. *
  3119. * Default: 300 (5 minutes)
  3120. */
  3121. #ifndef PJSUA_REG_RETRY_INTERVAL
  3122. # define PJSUA_REG_RETRY_INTERVAL 300
  3123. #endif
  3124. /**
  3125. * When the registration is successfull, the auto registration refresh will
  3126. * be sent before it expires. Setting this to 0 will disable it.
  3127. * This is useful for app that uses Push Notification and doesn't require auto
  3128. * registration refresh. App can periodically send refresh registration or
  3129. * send it before making a call.=
  3130. * See https://github.com/pjsip/pjproject/pull/2652 for more info.
  3131. *
  3132. * Default: 1 (enabled)
  3133. */
  3134. #ifndef PJSUA_REG_AUTO_REG_REFRESH
  3135. # define PJSUA_REG_AUTO_REG_REFRESH 1
  3136. #endif
  3137. /**
  3138. * This macro specifies the default value for \a contact_rewrite_method
  3139. * field in pjsua_acc_config. It specifies how Contact update will be
  3140. * done with the registration, if \a allow_contact_rewrite is enabled in
  3141. * the account config. See \a pjsua_contact_rewrite_method for the options.
  3142. *
  3143. * Value PJSUA_CONTACT_REWRITE_UNREGISTER(1) is the legacy behavior.
  3144. *
  3145. * Default value: PJSUA_CONTACT_REWRITE_NO_UNREG(2) |
  3146. * PJSUA_CONTACT_REWRITE_ALWAYS_UPDATE(4)
  3147. */
  3148. #ifndef PJSUA_CONTACT_REWRITE_METHOD
  3149. # define PJSUA_CONTACT_REWRITE_METHOD (PJSUA_CONTACT_REWRITE_NO_UNREG | \
  3150. PJSUA_CONTACT_REWRITE_ALWAYS_UPDATE)
  3151. #endif
  3152. /**
  3153. * Bit value used in pjsua_acc_config.reg_use_proxy field to indicate that
  3154. * the global outbound proxy list should be added to the REGISTER request.
  3155. */
  3156. #define PJSUA_REG_USE_OUTBOUND_PROXY 1
  3157. /**
  3158. * Bit value used in pjsua_acc_config.reg_use_proxy field to indicate that
  3159. * the account proxy list should be added to the REGISTER request.
  3160. */
  3161. #define PJSUA_REG_USE_ACC_PROXY 2
  3162. /**
  3163. * This enumeration specifies how we should offer call hold request to
  3164. * remote peer. The default value is set by compile time constant
  3165. * PJSUA_CALL_HOLD_TYPE_DEFAULT, and application may control the setting
  3166. * on per-account basis by manipulating \a call_hold_type field in
  3167. * #pjsua_acc_config.
  3168. */
  3169. typedef enum pjsua_call_hold_type
  3170. {
  3171. /**
  3172. * This will follow RFC 3264 recommendation to use a=sendonly,
  3173. * a=recvonly, and a=inactive attribute as means to signal call
  3174. * hold status. This is the correct value to use.
  3175. */
  3176. PJSUA_CALL_HOLD_TYPE_RFC3264,
  3177. /**
  3178. * This will use the old and deprecated method as specified in RFC 2543,
  3179. * and will offer c=0.0.0.0 in the SDP instead. Using this has many
  3180. * drawbacks such as inability to keep the media transport alive while
  3181. * the call is being put on hold, and should only be used if remote
  3182. * does not understand RFC 3264 style call hold offer.
  3183. */
  3184. PJSUA_CALL_HOLD_TYPE_RFC2543
  3185. } pjsua_call_hold_type;
  3186. /**
  3187. * Specify the default call hold type to be used in #pjsua_acc_config.
  3188. *
  3189. * Default is PJSUA_CALL_HOLD_TYPE_RFC3264, and there's no reason to change
  3190. * this except if you're communicating with an old/non-standard peer.
  3191. */
  3192. #ifndef PJSUA_CALL_HOLD_TYPE_DEFAULT
  3193. # define PJSUA_CALL_HOLD_TYPE_DEFAULT PJSUA_CALL_HOLD_TYPE_RFC3264
  3194. #endif
  3195. /**
  3196. * This enumeration controls the use of STUN in the account.
  3197. */
  3198. typedef enum pjsua_stun_use
  3199. {
  3200. /**
  3201. * Follow the default setting in the global \a pjsua_config.
  3202. */
  3203. PJSUA_STUN_USE_DEFAULT,
  3204. /**
  3205. * Disable STUN. If STUN is not enabled in the global \a pjsua_config,
  3206. * this setting has no effect.
  3207. */
  3208. PJSUA_STUN_USE_DISABLED,
  3209. /**
  3210. * Retry other STUN servers if the STUN server selected during
  3211. * startup (#pjsua_init()) or after calling #pjsua_update_stun_servers()
  3212. * is unavailable during runtime. This setting is valid only for
  3213. * account's media STUN setting and if the call is using UDP media
  3214. * transport.
  3215. */
  3216. PJSUA_STUN_RETRY_ON_FAILURE
  3217. } pjsua_stun_use;
  3218. /**
  3219. * This enumeration controls the use of UPnP in the account.
  3220. */
  3221. typedef enum pjsua_upnp_use
  3222. {
  3223. /**
  3224. * Follow the default setting in the global \a pjsua_config.
  3225. */
  3226. PJSUA_UPNP_USE_DEFAULT,
  3227. /**
  3228. * Disable UPnP.
  3229. */
  3230. PJSUA_UPNP_USE_DISABLED
  3231. } pjsua_upnp_use;
  3232. /**
  3233. * This enumeration controls the use of ICE settings in the account.
  3234. */
  3235. typedef enum pjsua_ice_config_use
  3236. {
  3237. /**
  3238. * Use the default settings in the global \a pjsua_media_config.
  3239. */
  3240. PJSUA_ICE_CONFIG_USE_DEFAULT,
  3241. /**
  3242. * Use the custom \a pjsua_ice_config setting in the account.
  3243. */
  3244. PJSUA_ICE_CONFIG_USE_CUSTOM
  3245. } pjsua_ice_config_use;
  3246. /**
  3247. * This enumeration controls the use of TURN settings in the account.
  3248. */
  3249. typedef enum pjsua_turn_config_use
  3250. {
  3251. /**
  3252. * Use the default setting in the global \a pjsua_media_config.
  3253. */
  3254. PJSUA_TURN_CONFIG_USE_DEFAULT,
  3255. /**
  3256. * Use the custom \a pjsua_turn_config setting in the account.
  3257. */
  3258. PJSUA_TURN_CONFIG_USE_CUSTOM
  3259. } pjsua_turn_config_use;
  3260. /**
  3261. * ICE setting. This setting is used in the pjsua_acc_config.
  3262. */
  3263. typedef struct pjsua_ice_config
  3264. {
  3265. /**
  3266. * Enable ICE.
  3267. */
  3268. pj_bool_t enable_ice;
  3269. /**
  3270. * Set the maximum number of host candidates.
  3271. *
  3272. * Default: -1 (maximum not set)
  3273. */
  3274. int ice_max_host_cands;
  3275. /**
  3276. * ICE session options.
  3277. */
  3278. pj_ice_sess_options ice_opt;
  3279. /**
  3280. * Disable RTCP component.
  3281. *
  3282. * Default: no
  3283. */
  3284. pj_bool_t ice_no_rtcp;
  3285. /**
  3286. * Send re-INVITE/UPDATE every after ICE connectivity check regardless
  3287. * the default ICE transport address is changed or not. When this is set
  3288. * to PJ_FALSE, re-INVITE/UPDATE will be sent only when the default ICE
  3289. * transport address is changed.
  3290. *
  3291. * Default: yes
  3292. */
  3293. pj_bool_t ice_always_update;
  3294. } pjsua_ice_config;
  3295. /**
  3296. * TURN setting. This setting is used in the pjsua_acc_config.
  3297. */
  3298. typedef struct pjsua_turn_config
  3299. {
  3300. /**
  3301. * Enable TURN candidate in ICE.
  3302. */
  3303. pj_bool_t enable_turn;
  3304. /**
  3305. * Specify TURN domain name or host name, in in "DOMAIN:PORT" or
  3306. * "HOST:PORT" format.
  3307. */
  3308. pj_str_t turn_server;
  3309. /**
  3310. * Specify the connection type to be used to the TURN server. Valid
  3311. * values are PJ_TURN_TP_UDP, PJ_TURN_TP_TCP or PJ_TURN_TP_TLS.
  3312. *
  3313. * Default: PJ_TURN_TP_UDP
  3314. */
  3315. pj_turn_tp_type turn_conn_type;
  3316. /**
  3317. * Specify the credential to authenticate with the TURN server.
  3318. */
  3319. pj_stun_auth_cred turn_auth_cred;
  3320. /**
  3321. * This specifies TLS settings for TURN TLS. It’s only applicable when
  3322. * TLS is used to connect to the TURN server.
  3323. */
  3324. pj_turn_sock_tls_cfg turn_tls_setting;
  3325. } pjsua_turn_config;
  3326. /**
  3327. * Specify how IPv6 transport should be used in account config.
  3328. * IP version preference only applies for outgoing direction, for incoming
  3329. * direction, we will check the corresponding message/offer and match it.
  3330. */
  3331. typedef enum pjsua_ipv6_use
  3332. {
  3333. /**
  3334. * IPv6 is not used.
  3335. */
  3336. PJSUA_IPV6_DISABLED,
  3337. /**
  3338. * IPv6 is enabled.
  3339. */
  3340. PJSUA_IPV6_ENABLED = 1,
  3341. PJSUA_IPV6_ENABLED_NO_PREFERENCE = 1,
  3342. /**
  3343. * IPv6 is enabled, but IPv4 is preferable.
  3344. */
  3345. PJSUA_IPV6_ENABLED_PREFER_IPV4,
  3346. /**
  3347. * IPv6 is enabled and preferable.
  3348. */
  3349. PJSUA_IPV6_ENABLED_PREFER_IPV6,
  3350. /**
  3351. * Only IPv6 is enabled, IPv4 will not be used.
  3352. */
  3353. PJSUA_IPV6_ENABLED_USE_IPV6_ONLY
  3354. } pjsua_ipv6_use;
  3355. /**
  3356. * Specify NAT64 options to be used in account config.
  3357. */
  3358. typedef enum pjsua_nat64_opt
  3359. {
  3360. /**
  3361. * NAT64 is not used.
  3362. */
  3363. PJSUA_NAT64_DISABLED,
  3364. /**
  3365. * NAT64 is enabled.
  3366. */
  3367. PJSUA_NAT64_ENABLED
  3368. } pjsua_nat64_opt;
  3369. /**
  3370. * This structure describes account configuration to be specified when
  3371. * adding a new account with #pjsua_acc_add(). Application MUST initialize
  3372. * this structure first by calling #pjsua_acc_config_default().
  3373. */
  3374. typedef struct pjsua_acc_config
  3375. {
  3376. /**
  3377. * Arbitrary user data to be associated with the newly created account.
  3378. * Application may set this later with #pjsua_acc_set_user_data() and
  3379. * retrieve it with #pjsua_acc_get_user_data().
  3380. */
  3381. void *user_data;
  3382. /**
  3383. * Account priority, which is used to control the order of matching
  3384. * incoming/outgoing requests. The higher the number means the higher
  3385. * the priority is, and the account will be matched first.
  3386. */
  3387. int priority;
  3388. /**
  3389. * The full SIP URL for the account. The value can take name address or
  3390. * URL format, and will look something like "sip:account@serviceprovider"
  3391. * or "\"Display Name\" <sip:account@provider>".
  3392. *
  3393. * This field is mandatory.
  3394. */
  3395. pj_str_t id;
  3396. /**
  3397. * This is the URL to be put in the request URI for the registration,
  3398. * and will look something like "sip:serviceprovider".
  3399. *
  3400. * This field should be specified if registration is desired. If the
  3401. * value is empty, no account registration will be performed.
  3402. */
  3403. pj_str_t reg_uri;
  3404. /**
  3405. * The optional custom SIP headers to be put in the registration
  3406. * request.
  3407. */
  3408. pjsip_hdr reg_hdr_list;
  3409. /**
  3410. * Additional parameters that will be appended in the Contact header
  3411. * for this account. This will only affect REGISTER requests and
  3412. * will be appended after \a contact_params;
  3413. *
  3414. * The parameters should be preceeded by semicolon, and all strings must
  3415. * be properly escaped. Example:
  3416. * ";my-param=X;another-param=Hi%20there"
  3417. */
  3418. pj_str_t reg_contact_params;
  3419. /**
  3420. * Additional URI parameters that will be appended in the Contact URI
  3421. * for this account. This will only affect REGISTER requests and
  3422. * will be appended after \a contact_uri_params;
  3423. *
  3424. * The parameters should be preceeded by semicolon, and all strings must
  3425. * be properly escaped. Example:
  3426. * ";my-param=X;another-param=Hi%20there"
  3427. */
  3428. pj_str_t reg_contact_uri_params;
  3429. /**
  3430. * The optional custom SIP headers to be put in the presence
  3431. * subscription request.
  3432. */
  3433. pjsip_hdr sub_hdr_list;
  3434. /**
  3435. * Subscribe to message waiting indication events (RFC 3842).
  3436. *
  3437. * See also \a enable_unsolicited_mwi field on #pjsua_config.
  3438. *
  3439. * Default: no
  3440. */
  3441. pj_bool_t mwi_enabled;
  3442. /**
  3443. * Specify the default expiration time for Message Waiting Indication
  3444. * (RFC 3842) event subscription. This must not be zero.
  3445. *
  3446. * Default: PJSIP_MWI_DEFAULT_EXPIRES
  3447. */
  3448. unsigned mwi_expires;
  3449. /**
  3450. * If this flag is set, the presence information of this account will
  3451. * be PUBLISH-ed to the server where the account belongs.
  3452. *
  3453. * Default: PJ_FALSE
  3454. */
  3455. pj_bool_t publish_enabled;
  3456. /**
  3457. * Event publication options.
  3458. */
  3459. pjsip_publishc_opt publish_opt;
  3460. /**
  3461. * Maximum time to wait for unpublication transaction(s) to complete
  3462. * during shutdown process, before sending unregistration. The library
  3463. * tries to wait for the unpublication (un-PUBLISH) to complete before
  3464. * sending REGISTER request to unregister the account, during library
  3465. * shutdown process. If the value is set too short, it is possible that
  3466. * the unregistration is sent before unpublication completes, causing
  3467. * unpublication request to fail.
  3468. *
  3469. * Default: PJSUA_UNPUBLISH_MAX_WAIT_TIME_MSEC
  3470. */
  3471. unsigned unpublish_max_wait_time_msec;
  3472. /**
  3473. * Authentication preference.
  3474. */
  3475. pjsip_auth_clt_pref auth_pref;
  3476. /**
  3477. * Optional PIDF tuple ID for outgoing PUBLISH and NOTIFY. If this value
  3478. * is not specified, a random string will be used.
  3479. */
  3480. pj_str_t pidf_tuple_id;
  3481. /**
  3482. * Optional URI to be put as Contact for this account. It is recommended
  3483. * that this field is left empty, so that the value will be calculated
  3484. * automatically based on the transport address.
  3485. */
  3486. pj_str_t force_contact;
  3487. /**
  3488. * Additional parameters that will be appended in the Contact header
  3489. * for this account. This will affect the Contact header in all SIP
  3490. * messages sent on behalf of this account, including but not limited to
  3491. * REGISTER, INVITE, and SUBCRIBE requests or responses.
  3492. *
  3493. * The parameters should be preceeded by semicolon, and all strings must
  3494. * be properly escaped. Example:
  3495. * ";my-param=X;another-param=Hi%20there"
  3496. */
  3497. pj_str_t contact_params;
  3498. /**
  3499. * Additional URI parameters that will be appended in the Contact URI
  3500. * for this account. This will affect the Contact URI in all SIP
  3501. * messages sent on behalf of this account, including but not limited to
  3502. * REGISTER, INVITE, and SUBCRIBE requests or responses.
  3503. *
  3504. * The parameters should be preceeded by semicolon, and all strings must
  3505. * be properly escaped. Example:
  3506. * ";my-param=X;another-param=Hi%20there"
  3507. */
  3508. pj_str_t contact_uri_params;
  3509. /**
  3510. * Specify how support for reliable provisional response (100rel/
  3511. * PRACK) should be used for all sessions in this account. See the
  3512. * documentation of pjsua_100rel_use enumeration for more info.
  3513. *
  3514. * Default: The default value is taken from the value of
  3515. * require_100rel in pjsua_config.
  3516. */
  3517. pjsua_100rel_use require_100rel;
  3518. /**
  3519. * Specify the usage of Session Timers for all sessions. See the
  3520. * #pjsua_sip_timer_use for possible values.
  3521. *
  3522. * Default: PJSUA_SIP_TIMER_OPTIONAL
  3523. */
  3524. pjsua_sip_timer_use use_timer;
  3525. /**
  3526. * Specify Session Timer settings, see #pjsip_timer_setting.
  3527. */
  3528. pjsip_timer_setting timer_setting;
  3529. /**
  3530. * Number of proxies in the proxy array below.
  3531. */
  3532. unsigned proxy_cnt;
  3533. /**
  3534. * Optional URI of the proxies to be visited for all outgoing requests
  3535. * that are using this account (REGISTER, INVITE, etc). Application need
  3536. * to specify these proxies if the service provider requires that requests
  3537. * destined towards its network should go through certain proxies first
  3538. * (for example, border controllers).
  3539. *
  3540. * These proxies will be put in the route set for this account, with
  3541. * maintaining the orders (the first proxy in the array will be visited
  3542. * first). If global outbound proxies are configured in pjsua_config,
  3543. * then these account proxies will be placed after the global outbound
  3544. * proxies in the routeset.
  3545. */
  3546. pj_str_t proxy[PJSUA_ACC_MAX_PROXIES];
  3547. /**
  3548. * If remote sends SDP answer containing more than one format or codec in
  3549. * the media line, send re-INVITE or UPDATE with just one codec to lock
  3550. * which codec to use.
  3551. *
  3552. * Default: 1 (Yes). Set to zero to disable.
  3553. */
  3554. unsigned lock_codec;
  3555. /**
  3556. * Optional interval for registration, in seconds. If the value is zero,
  3557. * default interval will be used (PJSUA_REG_INTERVAL, 300 seconds).
  3558. */
  3559. unsigned reg_timeout;
  3560. /**
  3561. * Specify the number of seconds to refresh the client registration
  3562. * before the registration expires.
  3563. *
  3564. * Default: PJSIP_REGISTER_CLIENT_DELAY_BEFORE_REFRESH, 5 seconds
  3565. */
  3566. unsigned reg_delay_before_refresh;
  3567. /**
  3568. * Specify the maximum time to wait for unregistration requests to
  3569. * complete during library shutdown sequence.
  3570. *
  3571. * Default: PJSUA_UNREG_TIMEOUT
  3572. */
  3573. unsigned unreg_timeout;
  3574. /**
  3575. * Number of credentials in the credential array.
  3576. */
  3577. unsigned cred_count;
  3578. /**
  3579. * Array of credentials. If registration is desired, normally there should
  3580. * be at least one credential specified, to successfully authenticate
  3581. * against the service provider. More credentials can be specified, for
  3582. * example when the requests are expected to be challenged by the
  3583. * proxies in the route set.
  3584. */
  3585. pjsip_cred_info cred_info[PJSUA_ACC_MAX_PROXIES];
  3586. /**
  3587. * Optionally bind this account to specific transport. This normally is
  3588. * not a good idea, as account should be able to send requests using
  3589. * any available transports according to the destination. But some
  3590. * application may want to have explicit control over the transport to
  3591. * use, so in that case it can set this field.
  3592. *
  3593. * Default: -1 (PJSUA_INVALID_ID)
  3594. *
  3595. * @see pjsua_acc_set_transport()
  3596. */
  3597. pjsua_transport_id transport_id;
  3598. /**
  3599. * This option is used to update the transport address and the Contact
  3600. * header of REGISTER request. When this option is enabled, the library
  3601. * will keep track of the public IP address from the response of REGISTER
  3602. * request. Once it detects that the address has changed, it will
  3603. * unregister current Contact, update the Contact with transport address
  3604. * learned from Via header, and register a new Contact to the registrar.
  3605. * This will also update the public name of UDP transport if STUN is
  3606. * configured.
  3607. *
  3608. * Possible values:
  3609. * * 0 (disabled).
  3610. * * 1 (enabled). Update except if both Contact and server's IP address
  3611. * are public but response contains private IP.
  3612. * * 2 (enabled). Update without exception.
  3613. *
  3614. * See also contact_rewrite_method field.
  3615. *
  3616. * Default: 1
  3617. */
  3618. pj_bool_t allow_contact_rewrite;
  3619. /**
  3620. * Specify how Contact update will be done with the registration, if
  3621. * \a allow_contact_rewrite is enabled. The value is bitmask combination of
  3622. * \a pjsua_contact_rewrite_method. See also pjsua_contact_rewrite_method.
  3623. *
  3624. * Value PJSUA_CONTACT_REWRITE_UNREGISTER(1) is the legacy behavior.
  3625. *
  3626. * Default value: PJSUA_CONTACT_REWRITE_METHOD
  3627. * (PJSUA_CONTACT_REWRITE_NO_UNREG | PJSUA_CONTACT_REWRITE_ALWAYS_UPDATE)
  3628. */
  3629. int contact_rewrite_method;
  3630. /**
  3631. * Specify if source TCP port should be used as the initial Contact
  3632. * address if TCP/TLS transport is used. Note that this feature will
  3633. * be automatically turned off when nameserver is configured because
  3634. * it may yield different destination address due to DNS SRV resolution.
  3635. * Also some platforms are unable to report the local address of the
  3636. * TCP socket when it is still connecting. In these cases, this
  3637. * feature will also be turned off.
  3638. *
  3639. * Default: PJ_TRUE (yes).
  3640. */
  3641. pj_bool_t contact_use_src_port;
  3642. /**
  3643. * This option is used to overwrite the "sent-by" field of the Via header
  3644. * for outgoing messages with the same interface address as the one in
  3645. * the REGISTER request, as long as the request uses the same transport
  3646. * instance as the previous REGISTER request.
  3647. *
  3648. * Default: 1 (yes)
  3649. */
  3650. pj_bool_t allow_via_rewrite;
  3651. /**
  3652. * This option controls whether the IP address in SDP should be replaced
  3653. * with the IP address found in Via header of the REGISTER response, ONLY
  3654. * when STUN and ICE are not used. If the value is FALSE (the original
  3655. * behavior), then the local IP address will be used. If TRUE, and when
  3656. * STUN and ICE are disabled, then the IP address found in registration
  3657. * response will be used.
  3658. *
  3659. * Default: PJ_FALSE (no)
  3660. */
  3661. pj_bool_t allow_sdp_nat_rewrite;
  3662. /**
  3663. * Control the use of SIP outbound feature. SIP outbound is described in
  3664. * RFC 5626 to enable proxies or registrar to send inbound requests back
  3665. * to UA using the same connection initiated by the UA for its
  3666. * registration. This feature is highly useful in NAT-ed deployemtns,
  3667. * hence it is enabled by default.
  3668. *
  3669. * Note: currently SIP outbound can only be used with TCP and TLS
  3670. * transports. If UDP is used for the registration, the SIP outbound
  3671. * feature will be silently ignored for the account.
  3672. *
  3673. * Default: PJ_TRUE
  3674. */
  3675. unsigned use_rfc5626;
  3676. /**
  3677. * Specify SIP outbound (RFC 5626) instance ID to be used by this
  3678. * application. If empty, an instance ID will be generated based on
  3679. * the hostname of this agent. If application specifies this parameter, the
  3680. * value will look like "<urn:uuid:00000000-0000-1000-8000-AABBCCDDEEFF>"
  3681. * without the doublequote.
  3682. *
  3683. * Default: empty
  3684. */
  3685. pj_str_t rfc5626_instance_id;
  3686. /**
  3687. * Specify SIP outbound (RFC 5626) registration ID. The default value
  3688. * is empty, which would cause the library to automatically generate
  3689. * a suitable value.
  3690. *
  3691. * Default: empty
  3692. */
  3693. pj_str_t rfc5626_reg_id;
  3694. /**
  3695. * Set the interval for periodic keep-alive transmission for this account.
  3696. * If this value is zero, keep-alive will be disabled for this account.
  3697. * The keep-alive transmission will be sent to the registrar's address,
  3698. * after successful registration.
  3699. *
  3700. * Default: 15 (seconds)
  3701. */
  3702. unsigned ka_interval;
  3703. /**
  3704. * Specify the data to be transmitted as keep-alive packets.
  3705. *
  3706. * Default: CR-LF
  3707. */
  3708. pj_str_t ka_data;
  3709. /**
  3710. * Specify whether incoming video should be shown to screen by default.
  3711. * This applies to incoming call (INVITE), incoming re-INVITE, and
  3712. * incoming UPDATE requests.
  3713. *
  3714. * Regardless of this setting, application can detect incoming video
  3715. * by implementing \a on_call_media_state() callback and enumerating
  3716. * the media stream(s) with #pjsua_call_get_info(). Once incoming
  3717. * video is recognised, application may retrieve the window associated
  3718. * with the incoming video and show or hide it with
  3719. * #pjsua_vid_win_set_show().
  3720. *
  3721. * Default: PJ_FALSE
  3722. */
  3723. pj_bool_t vid_in_auto_show;
  3724. /**
  3725. * Specify whether outgoing video should be activated by default when
  3726. * making outgoing calls and/or when incoming video is detected. This
  3727. * applies to incoming and outgoing calls, incoming re-INVITE, and
  3728. * incoming UPDATE. If the setting is non-zero, outgoing video
  3729. * transmission will be started as soon as response to these requests
  3730. * is sent (or received).
  3731. *
  3732. * Regardless of the value of this setting, application can start and
  3733. * stop outgoing video transmission with #pjsua_call_set_vid_strm().
  3734. *
  3735. * Default: PJ_FALSE
  3736. */
  3737. pj_bool_t vid_out_auto_transmit;
  3738. /**
  3739. * Specify video window's flags. The value is a bitmask combination of
  3740. * #pjmedia_vid_dev_wnd_flag.
  3741. *
  3742. * Default: 0
  3743. */
  3744. unsigned vid_wnd_flags;
  3745. /**
  3746. * Specify the default capture device to be used by this account. If
  3747. * \a vid_out_auto_transmit is enabled, this device will be used for
  3748. * capturing video.
  3749. *
  3750. * Default: PJMEDIA_VID_DEFAULT_CAPTURE_DEV
  3751. */
  3752. pjmedia_vid_dev_index vid_cap_dev;
  3753. /**
  3754. * Specify the default rendering device to be used by this account.
  3755. *
  3756. * Default: PJMEDIA_VID_DEFAULT_RENDER_DEV
  3757. */
  3758. pjmedia_vid_dev_index vid_rend_dev;
  3759. /**
  3760. * Specify the send rate control for video stream.
  3761. *
  3762. * Default: see #pjmedia_vid_stream_rc_config
  3763. */
  3764. pjmedia_vid_stream_rc_config vid_stream_rc_cfg;
  3765. /**
  3766. * Specify the send keyframe config for video stream.
  3767. *
  3768. * Default: see #pjmedia_vid_stream_sk_config
  3769. */
  3770. pjmedia_vid_stream_sk_config vid_stream_sk_cfg;
  3771. /**
  3772. * Media transport config.
  3773. *
  3774. * For \a port and \a port_range settings, RTCP port is selected as
  3775. * RTP port+1.
  3776. * Example: \a port=5000, \a port_range=4
  3777. * - Available ports: 5000, 5002, 5004 (Media/RTP transport)
  3778. * 5001, 5003, 5005 (Media/RTCP transport)
  3779. */
  3780. pjsua_transport_config rtp_cfg;
  3781. /**
  3782. * Specify NAT64 options.
  3783. *
  3784. * Default: PJSUA_NAT64_DISABLED
  3785. */
  3786. pjsua_nat64_opt nat64_opt;
  3787. /**
  3788. * Specify whether IPv6 should be used for SIP signalling.
  3789. *
  3790. * Default: PJSUA_IPV6_ENABLED_NO_PREFERENCE
  3791. * (IP version used will be based on the address resolution
  3792. * returned by OS/resolver)
  3793. */
  3794. pjsua_ipv6_use ipv6_sip_use;
  3795. /**
  3796. * Specify whether IPv6 should be used on media.
  3797. *
  3798. * Default: PJSUA_IPV6_ENABLED_PREFER_IPV4
  3799. * (Dual stack media, capable to use IPv4/IPv6.
  3800. * Outgoing offer will prefer to use IPv4)
  3801. */
  3802. pjsua_ipv6_use ipv6_media_use;
  3803. /**
  3804. * Control the use of STUN for the SIP signaling.
  3805. *
  3806. * Default: PJSUA_STUN_USE_DEFAULT
  3807. */
  3808. pjsua_stun_use sip_stun_use;
  3809. /**
  3810. * Control the use of STUN for the media transports.
  3811. *
  3812. * Default: PJSUA_STUN_RETRY_ON_FAILURE
  3813. */
  3814. pjsua_stun_use media_stun_use;
  3815. /**
  3816. * Control the use of UPnP for the SIP signaling.
  3817. *
  3818. * Default: PJSUA_UPNP_USE_DEFAULT
  3819. */
  3820. pjsua_upnp_use sip_upnp_use;
  3821. /**
  3822. * Control the use of UPnP for the media transports.
  3823. *
  3824. * Default: PJSUA_UPNP_USE_DEFAULT
  3825. */
  3826. pjsua_upnp_use media_upnp_use;
  3827. /**
  3828. * Use loopback media transport. This may be useful if application
  3829. * doesn't want PJSIP to create real media transports/sockets, such as
  3830. * when using third party media.
  3831. *
  3832. * Default: PJ_FALSE
  3833. */
  3834. pj_bool_t use_loop_med_tp;
  3835. /**
  3836. * Enable local loopback when loop_med_tp_use is set to PJ_TRUE.
  3837. * If enabled, packets sent to the transport will be sent back to
  3838. * the streams attached to the transport.
  3839. *
  3840. * Default: PJ_FALSE
  3841. */
  3842. pj_bool_t enable_loopback;
  3843. /**
  3844. * Control the use of ICE in the account. By default, the settings in the
  3845. * \a pjsua_media_config will be used.
  3846. *
  3847. * Default: PJSUA_ICE_CONFIG_USE_DEFAULT
  3848. */
  3849. pjsua_ice_config_use ice_cfg_use;
  3850. /**
  3851. * The custom ICE setting for this account. This setting will only be
  3852. * used if \a ice_cfg_use is set to PJSUA_ICE_CONFIG_USE_CUSTOM
  3853. */
  3854. pjsua_ice_config ice_cfg;
  3855. /**
  3856. * Control the use of TURN in the account. By default, the settings in the
  3857. * \a pjsua_media_config will be used
  3858. *
  3859. * Default: PJSUA_TURN_CONFIG_USE_DEFAULT
  3860. */
  3861. pjsua_turn_config_use turn_cfg_use;
  3862. /**
  3863. * The custom TURN setting for this account. This setting will only be
  3864. * used if \a turn_cfg_use is set to PJSUA_TURN_CONFIG_USE_CUSTOM
  3865. */
  3866. pjsua_turn_config turn_cfg;
  3867. /**
  3868. * Specify whether secure media transport should be used for this account.
  3869. * Valid values are PJMEDIA_SRTP_DISABLED, PJMEDIA_SRTP_OPTIONAL, and
  3870. * PJMEDIA_SRTP_MANDATORY.
  3871. *
  3872. * Default: #PJSUA_DEFAULT_USE_SRTP
  3873. */
  3874. pjmedia_srtp_use use_srtp;
  3875. /**
  3876. * Specify whether SRTP requires secure signaling to be used. This option
  3877. * is only used when \a use_srtp option above is non-zero.
  3878. *
  3879. * Valid values are:
  3880. * 0: SRTP does not require secure signaling
  3881. * 1: SRTP requires secure transport such as TLS
  3882. * 2: SRTP requires secure end-to-end transport (SIPS)
  3883. *
  3884. * Default: #PJSUA_DEFAULT_SRTP_SECURE_SIGNALING
  3885. */
  3886. int srtp_secure_signaling;
  3887. /**
  3888. * This setting has been deprecated and will be ignored.
  3889. */
  3890. pj_bool_t srtp_optional_dup_offer;
  3891. /**
  3892. * Specify SRTP transport setting. Application can initialize it with
  3893. * default values using pjsua_srtp_opt_default().
  3894. */
  3895. pjsua_srtp_opt srtp_opt;
  3896. /**
  3897. * Specify interval of auto registration retry upon registration failure,
  3898. * in seconds. Set to 0 to disable auto re-registration. Note that
  3899. * registration will only be automatically retried for temporal failures
  3900. * considered to be recoverable in relatively short term, such as:
  3901. * 408 (Request Timeout), 480 (Temporarily Unavailable),
  3902. * 500 (Internal Server Error), 502 (Bad Gateway),
  3903. * 503 (Service Unavailable), 504 (Server Timeout),
  3904. * 6xx (global failure), and failure caused by transport problem.
  3905. * For registration retry caused by transport failure, the first retry
  3906. * will be done after \a reg_first_retry_interval seconds instead.
  3907. * Note that the interval will be randomized slightly by some seconds
  3908. * (specified in \a reg_retry_random_interval) to avoid all clients
  3909. * re-registering at the same time.
  3910. *
  3911. * See also \a reg_first_retry_interval setting.
  3912. *
  3913. * Default: #PJSUA_REG_RETRY_INTERVAL
  3914. */
  3915. unsigned reg_retry_interval;
  3916. /**
  3917. * This specifies the interval for the first registration retry. The
  3918. * registration retry is explained in \a reg_retry_interval. Note that
  3919. * the value here will also be randomized by some seconds (specified
  3920. * in \a reg_retry_random_interval) to avoid all clients re-registering
  3921. * at the same time.
  3922. *
  3923. * Default: 0
  3924. */
  3925. unsigned reg_first_retry_interval;
  3926. /**
  3927. * This specifies maximum randomized value to be added/substracted
  3928. * to/from the registration retry interval specified in \a
  3929. * reg_retry_interval and \a reg_first_retry_interval, in second.
  3930. * This is useful to avoid all clients re-registering at the same time.
  3931. * For example, if the registration retry interval is set to 100 seconds
  3932. * and this is set to 10 seconds, the actual registration retry interval
  3933. * will be in the range of 90 to 110 seconds.
  3934. *
  3935. * Default: 10
  3936. */
  3937. unsigned reg_retry_random_interval;
  3938. /**
  3939. * Specify whether calls of the configured account should be dropped
  3940. * after registration failure and an attempt of re-registration has
  3941. * also failed.
  3942. *
  3943. * Default: PJ_FALSE (disabled)
  3944. */
  3945. pj_bool_t drop_calls_on_reg_fail;
  3946. /**
  3947. * Specify how the registration uses the outbound and account proxy
  3948. * settings. This controls if and what Route headers will appear in
  3949. * the REGISTER request of this account. The value is bitmask combination
  3950. * of PJSUA_REG_USE_OUTBOUND_PROXY and PJSUA_REG_USE_ACC_PROXY bits.
  3951. * If the value is set to 0, the REGISTER request will not use any proxy
  3952. * (i.e. it will not have any Route headers).
  3953. *
  3954. * Default: 3 (PJSUA_REG_USE_OUTBOUND_PROXY | PJSUA_REG_USE_ACC_PROXY)
  3955. */
  3956. unsigned reg_use_proxy;
  3957. #if defined(PJMEDIA_STREAM_ENABLE_KA) && (PJMEDIA_STREAM_ENABLE_KA != 0)
  3958. /**
  3959. * Specify whether stream keep-alive and NAT hole punching with
  3960. * non-codec-VAD mechanism (see @ref PJMEDIA_STREAM_ENABLE_KA) is enabled
  3961. * for this account.
  3962. *
  3963. * Default: PJ_FALSE (disabled)
  3964. */
  3965. pj_bool_t use_stream_ka;
  3966. /**
  3967. * Specify the keepalive configuration for stream.
  3968. *
  3969. * Default: see #pjmedia_stream_ka_config
  3970. */
  3971. pjmedia_stream_ka_config stream_ka_cfg;
  3972. #endif
  3973. /**
  3974. * Specify how to offer call hold to remote peer. Please see the
  3975. * documentation on #pjsua_call_hold_type for more info.
  3976. *
  3977. * Default: PJSUA_CALL_HOLD_TYPE_DEFAULT
  3978. */
  3979. pjsua_call_hold_type call_hold_type;
  3980. /**
  3981. * Specify whether the account should register as soon as it is
  3982. * added to the UA. Application can set this to PJ_FALSE and control
  3983. * the registration manually with pjsua_acc_set_registration().
  3984. *
  3985. * Default: PJ_TRUE
  3986. */
  3987. pj_bool_t register_on_acc_add;
  3988. /**
  3989. * Specify whether account modification with pjsua_acc_modify() should
  3990. * automatically update registration if necessary, for example if
  3991. * account credentials change.
  3992. *
  3993. * Disable this when immediate registration is not desirable, such as
  3994. * during IP address change.
  3995. *
  3996. * Default: PJ_FALSE.
  3997. */
  3998. pj_bool_t disable_reg_on_modify;
  3999. /**
  4000. * Specify account configuration specific to IP address change used when
  4001. * calling #pjsua_handle_ip_change().
  4002. */
  4003. pjsua_ip_change_acc_cfg ip_change_cfg;
  4004. /**
  4005. * Enable RTP and RTCP multiplexing.
  4006. */
  4007. pj_bool_t enable_rtcp_mux;
  4008. /**
  4009. * RTCP Feedback configuration.
  4010. */
  4011. pjmedia_rtcp_fb_setting rtcp_fb_cfg;
  4012. /**
  4013. * Enable RTCP Extended Report (RTCP XR).
  4014. *
  4015. * Default: PJMEDIA_STREAM_ENABLE_XR
  4016. */
  4017. pj_bool_t enable_rtcp_xr;
  4018. } pjsua_acc_config;
  4019. /**
  4020. * Initialize ICE config from a media config. If the \a pool argument
  4021. * is NULL, a simple memcpy() will be used.
  4022. *
  4023. * @param pool Memory to duplicate strings.
  4024. * @param dst Destination config.
  4025. * @param src Source config.
  4026. */
  4027. PJ_DECL(void) pjsua_ice_config_from_media_config(pj_pool_t *pool,
  4028. pjsua_ice_config *dst,
  4029. const pjsua_media_config *src);
  4030. /**
  4031. * Clone. If the \a pool argument is NULL, a simple memcpy() will be used.
  4032. *
  4033. * @param pool Memory to duplicate strings.
  4034. * @param dst Destination config.
  4035. * @param src Source config.
  4036. */
  4037. PJ_DECL(void) pjsua_ice_config_dup( pj_pool_t *pool,
  4038. pjsua_ice_config *dst,
  4039. const pjsua_ice_config *src);
  4040. /**
  4041. * Initialize TURN config from a media config. If the \a pool argument
  4042. * is NULL, a simple memcpy() will be used.
  4043. *
  4044. * @param pool Memory to duplicate strings.
  4045. * @param dst Destination config.
  4046. * @param src Source config.
  4047. */
  4048. PJ_DECL(void) pjsua_turn_config_from_media_config(pj_pool_t *pool,
  4049. pjsua_turn_config *dst,
  4050. const pjsua_media_config *src);
  4051. /**
  4052. * Clone. If the \a pool argument is NULL, a simple memcpy() will be used.
  4053. *
  4054. * @param pool Memory to duplicate strings.
  4055. * @param dst Destination config.
  4056. * @param src Source config.
  4057. */
  4058. PJ_DECL(void) pjsua_turn_config_dup(pj_pool_t *pool,
  4059. pjsua_turn_config *dst,
  4060. const pjsua_turn_config *src);
  4061. /**
  4062. * Call this function to initialize SRTP config with default values.
  4063. *
  4064. * @param cfg The SRTP config to be initialized.
  4065. */
  4066. PJ_DECL(void) pjsua_srtp_opt_default(pjsua_srtp_opt *cfg);
  4067. /**
  4068. * Duplicate SRTP transport setting. If the \a pool argument is NULL,
  4069. * a simple memcpy() will be used.
  4070. *
  4071. * @param pool Memory to duplicate strings.
  4072. * @param dst Destination setting.
  4073. * @param src Source setting.
  4074. * @param check_str If set to TRUE, the function will check if strings
  4075. * are identical before copying. Identical strings
  4076. * will not be duplicated.
  4077. * If set to FALSE, all strings will be duplicated.
  4078. */
  4079. PJ_DECL(void) pjsua_srtp_opt_dup(pj_pool_t *pool, pjsua_srtp_opt *dst,
  4080. const pjsua_srtp_opt *src,
  4081. pj_bool_t check_str);
  4082. /**
  4083. * Call this function to initialize account config with default values.
  4084. *
  4085. * @param cfg The account config to be initialized.
  4086. */
  4087. PJ_DECL(void) pjsua_acc_config_default(pjsua_acc_config *cfg);
  4088. /**
  4089. * Duplicate account config.
  4090. *
  4091. * @param pool Pool to be used for duplicating the config.
  4092. * @param dst Destination configuration.
  4093. * @param src Source configuration.
  4094. */
  4095. PJ_DECL(void) pjsua_acc_config_dup(pj_pool_t *pool,
  4096. pjsua_acc_config *dst,
  4097. const pjsua_acc_config *src);
  4098. /**
  4099. * Account info. Application can query account info by calling
  4100. * #pjsua_acc_get_info().
  4101. */
  4102. typedef struct pjsua_acc_info
  4103. {
  4104. /**
  4105. * The account ID.
  4106. */
  4107. pjsua_acc_id id;
  4108. /**
  4109. * Flag to indicate whether this is the default account.
  4110. */
  4111. pj_bool_t is_default;
  4112. /**
  4113. * Account URI
  4114. */
  4115. pj_str_t acc_uri;
  4116. /**
  4117. * Flag to tell whether this account has registration setting
  4118. * (reg_uri is not empty).
  4119. */
  4120. pj_bool_t has_registration;
  4121. /**
  4122. * An up to date expiration interval for account registration session,
  4123. * PJSIP_EXPIRES_NOT_SPECIFIED if the account doesn't have reg session.
  4124. */
  4125. unsigned expires;
  4126. /**
  4127. * Last registration status code. If status code is zero, the account
  4128. * is currently not registered. Any other value indicates the SIP
  4129. * status code of the registration.
  4130. */
  4131. pjsip_status_code status;
  4132. /**
  4133. * Last registration error code. When the status field contains a SIP
  4134. * status code that indicates a registration failure, last registration
  4135. * error code contains the error code that causes the failure. In any
  4136. * other case, its value is zero.
  4137. */
  4138. pj_status_t reg_last_err;
  4139. /**
  4140. * String describing the registration status.
  4141. */
  4142. pj_str_t status_text;
  4143. /**
  4144. * Presence online status for this account.
  4145. */
  4146. pj_bool_t online_status;
  4147. /**
  4148. * Presence online status text.
  4149. */
  4150. pj_str_t online_status_text;
  4151. /**
  4152. * Extended RPID online status information.
  4153. */
  4154. pjrpid_element rpid;
  4155. /**
  4156. * Buffer that is used internally to store the status text.
  4157. */
  4158. char buf_[PJ_ERR_MSG_SIZE];
  4159. } pjsua_acc_info;
  4160. /**
  4161. * Get number of current accounts.
  4162. *
  4163. * @return Current number of accounts.
  4164. */
  4165. PJ_DECL(unsigned) pjsua_acc_get_count(void);
  4166. /**
  4167. * Check if the specified account ID is valid.
  4168. *
  4169. * @param acc_id Account ID to check.
  4170. *
  4171. * @return Non-zero if account ID is valid.
  4172. */
  4173. PJ_DECL(pj_bool_t) pjsua_acc_is_valid(pjsua_acc_id acc_id);
  4174. /**
  4175. * Set default account to be used when incoming and outgoing
  4176. * requests doesn't match any accounts.
  4177. *
  4178. * @param acc_id The account ID to be used as default.
  4179. *
  4180. * @return PJ_SUCCESS on success.
  4181. */
  4182. PJ_DECL(pj_status_t) pjsua_acc_set_default(pjsua_acc_id acc_id);
  4183. /**
  4184. * Get default account to be used when receiving incoming requests (calls),
  4185. * when the destination of the incoming call doesn't match any other
  4186. * accounts.
  4187. *
  4188. * @return The default account ID, or PJSUA_INVALID_ID if no
  4189. * default account is configured.
  4190. */
  4191. PJ_DECL(pjsua_acc_id) pjsua_acc_get_default(void);
  4192. /**
  4193. * Add a new account to pjsua. PJSUA must have been initialized (with
  4194. * #pjsua_init()) before calling this function. If registration is configured
  4195. * for this account, this function would also start the SIP registration
  4196. * session with the SIP registrar server. This SIP registration session
  4197. * will be maintained internally by the library, and application doesn't
  4198. * need to do anything to maintain the registration session.
  4199. *
  4200. *
  4201. * @param acc_cfg Account configuration.
  4202. * @param is_default If non-zero, this account will be set as the default
  4203. * account. The default account will be used when sending
  4204. * outgoing requests (e.g. making call) when no account is
  4205. * specified, and when receiving incoming requests when the
  4206. * request does not match any accounts. It is recommended
  4207. * that default account is set to local/LAN account.
  4208. * @param p_acc_id Pointer to receive account ID of the new account.
  4209. *
  4210. * @return PJ_SUCCESS on success, or the appropriate error code.
  4211. */
  4212. PJ_DECL(pj_status_t) pjsua_acc_add(const pjsua_acc_config *acc_cfg,
  4213. pj_bool_t is_default,
  4214. pjsua_acc_id *p_acc_id);
  4215. /**
  4216. * Add a local account. A local account is used to identify local endpoint
  4217. * instead of a specific user, and for this reason, a transport ID is needed
  4218. * to obtain the local address information.
  4219. *
  4220. * @param tid Transport ID to generate account address.
  4221. * @param is_default If non-zero, this account will be set as the default
  4222. * account. The default account will be used when sending
  4223. * outgoing requests (e.g. making call) when no account is
  4224. * specified, and when receiving incoming requests when the
  4225. * request does not match any accounts. It is recommended
  4226. * that default account is set to local/LAN account.
  4227. * @param p_acc_id Pointer to receive account ID of the new account.
  4228. *
  4229. * @return PJ_SUCCESS on success, or the appropriate error code.
  4230. */
  4231. PJ_DECL(pj_status_t) pjsua_acc_add_local(pjsua_transport_id tid,
  4232. pj_bool_t is_default,
  4233. pjsua_acc_id *p_acc_id);
  4234. /**
  4235. * Set arbitrary data to be associated with the account.
  4236. *
  4237. * @param acc_id The account ID.
  4238. * @param user_data User/application data.
  4239. *
  4240. * @return PJ_SUCCESS on success, or the appropriate error code.
  4241. */
  4242. PJ_DECL(pj_status_t) pjsua_acc_set_user_data(pjsua_acc_id acc_id,
  4243. void *user_data);
  4244. /**
  4245. * Retrieve arbitrary data associated with the account.
  4246. *
  4247. * @param acc_id The account ID.
  4248. *
  4249. * @return The user data. In the case where the account ID is
  4250. * not valid, NULL is returned.
  4251. */
  4252. PJ_DECL(void*) pjsua_acc_get_user_data(pjsua_acc_id acc_id);
  4253. /**
  4254. * Delete an account. This will unregister the account from the SIP server,
  4255. * if necessary, and terminate server side presence subscriptions associated
  4256. * with this account.
  4257. *
  4258. * @param acc_id Id of the account to be deleted.
  4259. *
  4260. * @return PJ_SUCCESS on success, or the appropriate error code.
  4261. */
  4262. PJ_DECL(pj_status_t) pjsua_acc_del(pjsua_acc_id acc_id);
  4263. /**
  4264. * Get current config for the account. This will copy current account setting
  4265. * to the specified parameter. Note that all pointers in the settings will
  4266. * point to the original settings in the account and application must not
  4267. * modify the values in any way. Application must also take care that these
  4268. * data is only valid until the account is destroyed.
  4269. *
  4270. * @param acc_id The account ID.
  4271. * @param pool Pool to duplicate the config.
  4272. * @param acc_cfg Structure to receive the settings.
  4273. *
  4274. * @return PJ_SUCCESS on success, or the appropriate error code.
  4275. */
  4276. PJ_DECL(pj_status_t) pjsua_acc_get_config(pjsua_acc_id acc_id,
  4277. pj_pool_t *pool,
  4278. pjsua_acc_config *acc_cfg);
  4279. /**
  4280. * Modify account configuration setting. This function may trigger
  4281. * unregistration (of old account setting) and re-registration (of the new
  4282. * account setting), e.g: changing account ID, credential, registar, or
  4283. * proxy setting.
  4284. *
  4285. * Note:
  4286. * - when the new config triggers unregistration, the pjsua callback
  4287. * on_reg_state()/on_reg_state2() for the unregistration will not be called
  4288. * and any failure in the unregistration will be ignored, so if application
  4289. * needs to be sure about the unregistration status, it should unregister
  4290. * manually and wait for the callback before calling this function
  4291. * - when the new config triggers re-registration and the re-registration
  4292. * fails, the account setting will not be reverted back to the old setting
  4293. * and the account will be in unregistered state.
  4294. *
  4295. * @param acc_id Id of the account to be modified.
  4296. * @param acc_cfg New account configuration.
  4297. *
  4298. * @return PJ_SUCCESS on success, or the appropriate error code.
  4299. */
  4300. PJ_DECL(pj_status_t) pjsua_acc_modify(pjsua_acc_id acc_id,
  4301. const pjsua_acc_config *acc_cfg);
  4302. /**
  4303. * Modify account's presence status to be advertised to remote/presence
  4304. * subscribers. This would trigger the sending of outgoing NOTIFY request
  4305. * if there are server side presence subscription for this account, and/or
  4306. * outgoing PUBLISH if presence publication is enabled for this account.
  4307. *
  4308. * @see pjsua_acc_set_online_status2()
  4309. *
  4310. * @param acc_id The account ID.
  4311. * @param is_online True of false.
  4312. *
  4313. * @return PJ_SUCCESS on success, or the appropriate error code.
  4314. */
  4315. PJ_DECL(pj_status_t) pjsua_acc_set_online_status(pjsua_acc_id acc_id,
  4316. pj_bool_t is_online);
  4317. /**
  4318. * Modify account's presence status to be advertised to remote/presence
  4319. * subscribers. This would trigger the sending of outgoing NOTIFY request
  4320. * if there are server side presence subscription for this account, and/or
  4321. * outgoing PUBLISH if presence publication is enabled for this account.
  4322. *
  4323. * @see pjsua_acc_set_online_status()
  4324. *
  4325. * @param acc_id The account ID.
  4326. * @param is_online True of false.
  4327. * @param pr Extended information in subset of RPID format
  4328. * which allows setting custom presence text.
  4329. *
  4330. * @return PJ_SUCCESS on success, or the appropriate error code.
  4331. */
  4332. PJ_DECL(pj_status_t) pjsua_acc_set_online_status2(pjsua_acc_id acc_id,
  4333. pj_bool_t is_online,
  4334. const pjrpid_element *pr);
  4335. /**
  4336. * Update registration or perform unregistration. If registration is
  4337. * configured for this account, then initial SIP REGISTER will be sent
  4338. * when the account is added with #pjsua_acc_add(). Application normally
  4339. * only need to call this function if it wants to manually update the
  4340. * registration or to unregister from the server.
  4341. *
  4342. * @param acc_id The account ID.
  4343. * @param renew If renew argument is zero, this will start
  4344. * unregistration process.
  4345. *
  4346. * @return PJ_SUCCESS on success, or the appropriate error code.
  4347. */
  4348. PJ_DECL(pj_status_t) pjsua_acc_set_registration(pjsua_acc_id acc_id,
  4349. pj_bool_t renew);
  4350. /**
  4351. * Get information about the specified account.
  4352. *
  4353. * @param acc_id Account identification.
  4354. * @param info Pointer to receive account information.
  4355. *
  4356. * @return PJ_SUCCESS on success, or the appropriate error code.
  4357. */
  4358. PJ_DECL(pj_status_t) pjsua_acc_get_info(pjsua_acc_id acc_id,
  4359. pjsua_acc_info *info);
  4360. /**
  4361. * Enumerate all account currently active in the library. This will fill
  4362. * the array with the account Ids, and application can then query the
  4363. * account information for each id with #pjsua_acc_get_info().
  4364. *
  4365. * @see pjsua_acc_enum_info().
  4366. *
  4367. * @param ids Array of account IDs to be initialized.
  4368. * @param count In input, specifies the maximum number of elements.
  4369. * On return, it contains the actual number of elements.
  4370. *
  4371. * @return PJ_SUCCESS on success, or the appropriate error code.
  4372. */
  4373. PJ_DECL(pj_status_t) pjsua_enum_accs(pjsua_acc_id ids[],
  4374. unsigned *count );
  4375. /**
  4376. * Enumerate account informations.
  4377. *
  4378. * @param info Array of account infos to be initialized.
  4379. * @param count In input, specifies the maximum number of elements.
  4380. * On return, it contains the actual number of elements.
  4381. *
  4382. * @return PJ_SUCCESS on success, or the appropriate error code.
  4383. */
  4384. PJ_DECL(pj_status_t) pjsua_acc_enum_info( pjsua_acc_info info[],
  4385. unsigned *count );
  4386. /**
  4387. * This is an internal function to find the most appropriate account to
  4388. * used to reach to the specified URL.
  4389. *
  4390. * @param url The remote URL to reach.
  4391. *
  4392. * @return Account id.
  4393. */
  4394. PJ_DECL(pjsua_acc_id) pjsua_acc_find_for_outgoing(const pj_str_t *url);
  4395. /**
  4396. * This is an internal function to find the most appropriate account to be
  4397. * used to handle incoming calls.
  4398. *
  4399. * @param rdata The incoming request message.
  4400. *
  4401. * @return Account id.
  4402. */
  4403. PJ_DECL(pjsua_acc_id) pjsua_acc_find_for_incoming(pjsip_rx_data *rdata);
  4404. /**
  4405. * Create arbitrary requests using the account. Application should only use
  4406. * this function to create auxiliary requests outside dialog, such as
  4407. * OPTIONS, and use the call or presence API to create dialog related
  4408. * requests.
  4409. *
  4410. * @param acc_id The account ID.
  4411. * @param method The SIP method of the request.
  4412. * @param target Target URI.
  4413. * @param p_tdata Pointer to receive the request.
  4414. *
  4415. * @return PJ_SUCCESS or the error code.
  4416. */
  4417. PJ_DECL(pj_status_t) pjsua_acc_create_request(pjsua_acc_id acc_id,
  4418. const pjsip_method *method,
  4419. const pj_str_t *target,
  4420. pjsip_tx_data **p_tdata);
  4421. /**
  4422. * Create a suitable Contact header value, based on the specified target URI
  4423. * for the specified account.
  4424. *
  4425. * @param pool Pool to allocate memory for the string.
  4426. * @param contact The string where the Contact will be stored.
  4427. * @param acc_id Account ID.
  4428. * @param uri Destination URI of the request.
  4429. *
  4430. * @return PJ_SUCCESS on success, other on error.
  4431. */
  4432. PJ_DECL(pj_status_t) pjsua_acc_create_uac_contact( pj_pool_t *pool,
  4433. pj_str_t *contact,
  4434. pjsua_acc_id acc_id,
  4435. const pj_str_t *uri);
  4436. /**
  4437. * Create a suitable Contact header value, based on the information in the
  4438. * incoming request.
  4439. *
  4440. * @param pool Pool to allocate memory for the string.
  4441. * @param contact The string where the Contact will be stored.
  4442. * @param acc_id Account ID.
  4443. * @param rdata Incoming request.
  4444. *
  4445. * @return PJ_SUCCESS on success, other on error.
  4446. */
  4447. PJ_DECL(pj_status_t) pjsua_acc_create_uas_contact( pj_pool_t *pool,
  4448. pj_str_t *contact,
  4449. pjsua_acc_id acc_id,
  4450. pjsip_rx_data *rdata );
  4451. /**
  4452. * Lock/bind this account to a specific transport/listener. Normally
  4453. * application shouldn't need to do this, as transports will be selected
  4454. * automatically by the stack according to the destination.
  4455. *
  4456. * When account is locked/bound to a specific transport, all outgoing
  4457. * requests from this account will use the specified transport (this
  4458. * includes SIP registration, dialog (call and event subscription), and
  4459. * out-of-dialog requests such as MESSAGE).
  4460. *
  4461. * Note that transport_id may be specified in pjsua_acc_config too.
  4462. *
  4463. * @param acc_id The account ID.
  4464. * @param tp_id The transport ID.
  4465. *
  4466. * @return PJ_SUCCESS on success.
  4467. */
  4468. PJ_DECL(pj_status_t) pjsua_acc_set_transport(pjsua_acc_id acc_id,
  4469. pjsua_transport_id tp_id);
  4470. /**
  4471. * @}
  4472. */
  4473. /*****************************************************************************
  4474. * CALLS API
  4475. */
  4476. /**
  4477. * @defgroup PJSUA_LIB_CALL PJSUA-API Calls Management
  4478. * @ingroup PJSUA_LIB
  4479. * @brief Call manipulation.
  4480. * @{
  4481. */
  4482. /**
  4483. * Maximum simultaneous calls.
  4484. */
  4485. #ifndef PJSUA_MAX_CALLS
  4486. # define PJSUA_MAX_CALLS 4
  4487. #endif
  4488. /**
  4489. * Maximum active video windows
  4490. */
  4491. #ifndef PJSUA_MAX_VID_WINS
  4492. # define PJSUA_MAX_VID_WINS 16
  4493. #endif
  4494. /**
  4495. * Specifies if lock codec feature should always use INVITE method.
  4496. * This will also affect ICE completion update in updating default address
  4497. * in SDP.
  4498. *
  4499. * This can be useful when communicating with endpoints that do not
  4500. * respond to UPDATE properly while indicating UPDATE support (by
  4501. * specifying UPDATE in its SIP Allow header).
  4502. *
  4503. * Note that UPDATE can be sent when dialog is still in early state,
  4504. * while re-INVITE needs to wait until the dialog is confirmed.
  4505. */
  4506. #ifndef PJSUA_LOCK_CODEC_DONT_USE_UPDATE
  4507. # define PJSUA_LOCK_CODEC_DONT_USE_UPDATE 0
  4508. #endif
  4509. /**
  4510. * Video window ID.
  4511. */
  4512. typedef int pjsua_vid_win_id;
  4513. /**
  4514. * This enumeration specifies the media status of a call, and it's part
  4515. * of pjsua_call_info structure.
  4516. */
  4517. typedef enum pjsua_call_media_status
  4518. {
  4519. /**
  4520. * Call currently has no media, or the media is not used.
  4521. */
  4522. PJSUA_CALL_MEDIA_NONE,
  4523. /**
  4524. * The media is active
  4525. */
  4526. PJSUA_CALL_MEDIA_ACTIVE,
  4527. /**
  4528. * The media is currently put on hold by local endpoint
  4529. */
  4530. PJSUA_CALL_MEDIA_LOCAL_HOLD,
  4531. /**
  4532. * The media is currently put on hold by remote endpoint
  4533. */
  4534. PJSUA_CALL_MEDIA_REMOTE_HOLD,
  4535. /**
  4536. * The media has reported error (e.g. ICE negotiation)
  4537. */
  4538. PJSUA_CALL_MEDIA_ERROR
  4539. } pjsua_call_media_status;
  4540. /**
  4541. * Enumeration of video keyframe request methods. Keyframe request is
  4542. * triggered by decoder, usually when the incoming video stream cannot
  4543. * be decoded properly due to missing video keyframe.
  4544. */
  4545. typedef enum pjsua_vid_req_keyframe_method
  4546. {
  4547. /**
  4548. * Requesting keyframe via SIP INFO message. Note that incoming keyframe
  4549. * request via SIP INFO will always be handled even if this flag is unset.
  4550. */
  4551. PJSUA_VID_REQ_KEYFRAME_SIP_INFO = 1,
  4552. /**
  4553. * Requesting keyframe via Picture Loss Indication of RTCP feedback.
  4554. */
  4555. PJSUA_VID_REQ_KEYFRAME_RTCP_PLI = 2
  4556. } pjsua_vid_req_keyframe_method;
  4557. /**
  4558. * Call media information.
  4559. */
  4560. typedef struct pjsua_call_media_info
  4561. {
  4562. /** Media index in SDP. */
  4563. unsigned index;
  4564. /** Media type. */
  4565. pjmedia_type type;
  4566. /** Media direction. */
  4567. pjmedia_dir dir;
  4568. /** Call media status. */
  4569. pjsua_call_media_status status;
  4570. /** The specific media stream info. */
  4571. union {
  4572. /** Audio stream */
  4573. struct {
  4574. /** The conference port number for the call. */
  4575. pjsua_conf_port_id conf_slot;
  4576. } aud;
  4577. /** Video stream */
  4578. struct {
  4579. /**
  4580. * The window id for incoming video, if any, or
  4581. * PJSUA_INVALID_ID.
  4582. */
  4583. pjsua_vid_win_id win_in;
  4584. /**
  4585. * The video conference port number for the call in decoding
  4586. * direction.
  4587. */
  4588. pjsua_conf_port_id dec_slot;
  4589. /**
  4590. * The video conference port number for the call in encoding
  4591. * direction.
  4592. */
  4593. pjsua_conf_port_id enc_slot;
  4594. /**
  4595. * The video capture device for outgoing transmission,
  4596. * if any, or PJMEDIA_VID_INVALID_DEV
  4597. */
  4598. pjmedia_vid_dev_index cap_dev;
  4599. } vid;
  4600. } stream;
  4601. } pjsua_call_media_info;
  4602. /**
  4603. * This structure describes the information and current status of a call.
  4604. */
  4605. typedef struct pjsua_call_info
  4606. {
  4607. /** Call identification. */
  4608. pjsua_call_id id;
  4609. /** Initial call role (UAC == caller) */
  4610. pjsip_role_e role;
  4611. /** The account ID where this call belongs. */
  4612. pjsua_acc_id acc_id;
  4613. /** Local URI */
  4614. pj_str_t local_info;
  4615. /** Local Contact */
  4616. pj_str_t local_contact;
  4617. /** Remote URI */
  4618. pj_str_t remote_info;
  4619. /** Remote contact */
  4620. pj_str_t remote_contact;
  4621. /** Dialog Call-ID string. */
  4622. pj_str_t call_id;
  4623. /** Call setting */
  4624. pjsua_call_setting setting;
  4625. /** Call state */
  4626. pjsip_inv_state state;
  4627. /** Text describing the state */
  4628. pj_str_t state_text;
  4629. /** Last status code heard, which can be used as cause code */
  4630. pjsip_status_code last_status;
  4631. /** The reason phrase describing the status. */
  4632. pj_str_t last_status_text;
  4633. /** Media status of the default audio stream. Default audio stream
  4634. * is chosen according to this priority:
  4635. * 1. enabled, i.e: SDP media port not zero
  4636. * 2. transport protocol in the SDP matching account config's
  4637. * secure media transport usage (\a use_srtp field).
  4638. * 3. active, i.e: SDP media direction is not "inactive"
  4639. * 4. media order (according to the SDP).
  4640. */
  4641. pjsua_call_media_status media_status;
  4642. /** Media direction of the default audio stream.
  4643. * See \a media_status above on how the default is chosen.
  4644. */
  4645. pjmedia_dir media_dir;
  4646. /** The conference port number for the default audio stream.
  4647. * See \a media_status above on how the default is chosen.
  4648. */
  4649. pjsua_conf_port_id conf_slot;
  4650. /** Number of active media info in this call. */
  4651. unsigned media_cnt;
  4652. /** Array of active media information. */
  4653. pjsua_call_media_info media[PJMEDIA_MAX_SDP_MEDIA];
  4654. /** Number of provisional media info in this call. */
  4655. unsigned prov_media_cnt;
  4656. /** Array of provisional media information. This contains the media info
  4657. * in the provisioning state, that is when the media session is being
  4658. * created/updated (SDP offer/answer is on progress).
  4659. */
  4660. pjsua_call_media_info prov_media[PJMEDIA_MAX_SDP_MEDIA];
  4661. /** Up-to-date call connected duration (zero when call is not
  4662. * established)
  4663. */
  4664. pj_time_val connect_duration;
  4665. /** Total call duration, including set-up time */
  4666. pj_time_val total_duration;
  4667. /** Flag if remote was SDP offerer */
  4668. pj_bool_t rem_offerer;
  4669. /** Number of audio streams offered by remote */
  4670. unsigned rem_aud_cnt;
  4671. /** Number of video streams offered by remote */
  4672. unsigned rem_vid_cnt;
  4673. /** Internal */
  4674. struct {
  4675. char local_info[PJSIP_MAX_URL_SIZE];
  4676. char local_contact[PJSIP_MAX_URL_SIZE];
  4677. char remote_info[PJSIP_MAX_URL_SIZE];
  4678. char remote_contact[PJSIP_MAX_URL_SIZE];
  4679. char call_id[128];
  4680. char last_status_text[128];
  4681. } buf_;
  4682. } pjsua_call_info;
  4683. /**
  4684. * Flags to be given to various call APIs. More than one flags may be
  4685. * specified by bitmasking them.
  4686. */
  4687. typedef enum pjsua_call_flag
  4688. {
  4689. /**
  4690. * When the call is being put on hold, specify this flag to unhold it.
  4691. * This flag is only valid for #pjsua_call_reinvite() and
  4692. * #pjsua_call_update(). Note: for compatibility reason, this flag must
  4693. * have value of 1 because previously the unhold option is specified as
  4694. * boolean value.
  4695. */
  4696. PJSUA_CALL_UNHOLD = 1,
  4697. /**
  4698. * Update the local invite session's contact with the contact URI from
  4699. * the account. This flag is only valid for #pjsua_call_set_hold2(),
  4700. * #pjsua_call_reinvite() and #pjsua_call_update(). This flag is useful
  4701. * in IP address change situation, after the local account's Contact has
  4702. * been updated (typically with re-registration) use this flag to update
  4703. * the invite session with the new Contact and to inform this new Contact
  4704. * to the remote peer with the outgoing re-INVITE or UPDATE.
  4705. */
  4706. PJSUA_CALL_UPDATE_CONTACT = 2,
  4707. /**
  4708. * Include SDP "m=" line with port set to zero for each disabled media
  4709. * (i.e when aud_cnt or vid_cnt is set to zero). This flag is only valid
  4710. * for #pjsua_call_make_call(), #pjsua_call_reinvite(), and
  4711. * #pjsua_call_update(). Note that even this flag is applicable in
  4712. * #pjsua_call_reinvite() and #pjsua_call_update(), it will only take
  4713. * effect when the re-INVITE/UPDATE operation regenerates SDP offer,
  4714. * such as changing audio or video count in the call setting.
  4715. */
  4716. PJSUA_CALL_INCLUDE_DISABLED_MEDIA = 4,
  4717. /**
  4718. * Do not send SDP when sending INVITE or UPDATE. This flag is only valid
  4719. * for #pjsua_call_make_call(), #pjsua_call_reinvite()/reinvite2(), or
  4720. * #pjsua_call_update()/update2(). For re-invite/update, specifying
  4721. * PJSUA_CALL_UNHOLD will take precedence over this flag.
  4722. */
  4723. PJSUA_CALL_NO_SDP_OFFER = 8,
  4724. /**
  4725. * Deinitialize and recreate media, including media transport. This flag
  4726. * is useful in IP address change situation, if the media transport
  4727. * address (or address family) changes, for example during IPv4/IPv6
  4728. * network handover.
  4729. * This flag is only valid for #pjsua_call_reinvite()/reinvite2(), or
  4730. * #pjsua_call_update()/update2().
  4731. *
  4732. * Warning: If the re-INVITE/UPDATE fails, the old media will not be
  4733. * reverted.
  4734. */
  4735. PJSUA_CALL_REINIT_MEDIA = 16,
  4736. /**
  4737. * Update the local invite session's Via with the via address from
  4738. * the account. This flag is only valid for #pjsua_call_set_hold2(),
  4739. * #pjsua_call_reinvite() and #pjsua_call_update(). Similar to
  4740. * the flag PJSUA_CALL_UPDATE_CONTACT above, this flag is useful
  4741. * in IP address change situation, after the local account's Via has
  4742. * been updated (typically with re-registration).
  4743. */
  4744. PJSUA_CALL_UPDATE_VIA = 32,
  4745. /**
  4746. * Update dialog target to URI specified in pjsua_msg_data.target_uri.
  4747. * This flag is only valid for pjsua_call_set_hold(),
  4748. * pjsua_call_reinvite(), and pjsua_call_update(). This flag can be
  4749. * useful in IP address change scenario where IP version has been changed
  4750. * and application needs to update target IP address.
  4751. */
  4752. PJSUA_CALL_UPDATE_TARGET = 64,
  4753. /**
  4754. * Set media direction as specified in pjsua_call_setting.media_dir.
  4755. */
  4756. PJSUA_CALL_SET_MEDIA_DIR = 128
  4757. } pjsua_call_flag;
  4758. /**
  4759. * This enumeration represents video stream operation on a call.
  4760. * See also #pjsua_call_vid_strm_op_param for further info.
  4761. */
  4762. typedef enum pjsua_call_vid_strm_op
  4763. {
  4764. /**
  4765. * No operation
  4766. */
  4767. PJSUA_CALL_VID_STRM_NO_OP,
  4768. /**
  4769. * Add a new video stream. This will add a new m=video line to
  4770. * the media, regardless of whether existing video is/are present
  4771. * or not. This will cause re-INVITE or UPDATE to be sent to remote
  4772. * party.
  4773. */
  4774. PJSUA_CALL_VID_STRM_ADD,
  4775. /**
  4776. * Remove/disable an existing video stream. This will
  4777. * cause re-INVITE or UPDATE to be sent to remote party.
  4778. */
  4779. PJSUA_CALL_VID_STRM_REMOVE,
  4780. /**
  4781. * Change direction of a video stream. This operation can be used
  4782. * to activate or deactivate an existing video media. This will
  4783. * cause re-INVITE or UPDATE to be sent to remote party.
  4784. */
  4785. PJSUA_CALL_VID_STRM_CHANGE_DIR,
  4786. /**
  4787. * Change capture device of a video stream. This will not send
  4788. * re-INVITE or UPDATE to remote party.
  4789. */
  4790. PJSUA_CALL_VID_STRM_CHANGE_CAP_DEV,
  4791. /**
  4792. * Start transmitting video stream. This will cause previously
  4793. * stopped stream to start transmitting again. Note that no
  4794. * re-INVITE/UPDATE is to be transmitted to remote since this
  4795. * operation only operates on local stream.
  4796. */
  4797. PJSUA_CALL_VID_STRM_START_TRANSMIT,
  4798. /**
  4799. * Stop transmitting video stream. This will cause the stream to
  4800. * be paused in TX direction, causing it to stop sending any video
  4801. * packets. No re-INVITE/UPDATE is to be transmitted to remote
  4802. * with this operation.
  4803. */
  4804. PJSUA_CALL_VID_STRM_STOP_TRANSMIT,
  4805. /**
  4806. * Send keyframe in the video stream. This will force the stream to
  4807. * generate and send video keyframe as soon as possible. No
  4808. * re-INVITE/UPDATE is to be transmitted to remote with this operation.
  4809. */
  4810. PJSUA_CALL_VID_STRM_SEND_KEYFRAME
  4811. } pjsua_call_vid_strm_op;
  4812. /**
  4813. * Parameters for video stream operation on a call. Application should
  4814. * use #pjsua_call_vid_strm_op_param_default() to initialize this structure
  4815. * with its default values.
  4816. */
  4817. typedef struct pjsua_call_vid_strm_op_param
  4818. {
  4819. /**
  4820. * Specify the media stream index. This can be set to -1 to denote
  4821. * the default video stream in the call, which is the first active
  4822. * video stream or any first video stream if none is active.
  4823. *
  4824. * This field is valid for all video stream operations, except
  4825. * PJSUA_CALL_VID_STRM_ADD.
  4826. *
  4827. * Default: -1 (first active video stream, or any first video stream
  4828. * if none is active)
  4829. */
  4830. int med_idx;
  4831. /**
  4832. * Specify the media stream direction.
  4833. *
  4834. * This field is valid for the following video stream operations:
  4835. * PJSUA_CALL_VID_STRM_ADD and PJSUA_CALL_VID_STRM_CHANGE_DIR.
  4836. *
  4837. * Default: PJMEDIA_DIR_ENCODING_DECODING
  4838. */
  4839. pjmedia_dir dir;
  4840. /**
  4841. * Specify the video capture device ID. This can be set to
  4842. * PJMEDIA_VID_DEFAULT_CAPTURE_DEV to specify the default capture
  4843. * device as configured in the account.
  4844. *
  4845. * This field is valid for the following video stream operations:
  4846. * PJSUA_CALL_VID_STRM_ADD and PJSUA_CALL_VID_STRM_CHANGE_CAP_DEV.
  4847. *
  4848. * Default: PJMEDIA_VID_DEFAULT_CAPTURE_DEV.
  4849. */
  4850. pjmedia_vid_dev_index cap_dev;
  4851. } pjsua_call_vid_strm_op_param;
  4852. /**
  4853. * Specify the default signal duration when sending DTMF using SIP INFO.
  4854. *
  4855. * Default is 160
  4856. */
  4857. #ifndef PJSUA_CALL_SEND_DTMF_DURATION_DEFAULT
  4858. # define PJSUA_CALL_SEND_DTMF_DURATION_DEFAULT 160
  4859. #endif
  4860. /**
  4861. * Parameters for sending DTMF. Application should use
  4862. * #pjsua_call_send_dtmf_param_default() to initialize this structure
  4863. * with its default values.
  4864. */
  4865. typedef struct pjsua_call_send_dtmf_param
  4866. {
  4867. /**
  4868. * The method used to send DTMF.
  4869. *
  4870. * Default: PJSUA_DTMF_METHOD_RFC2833
  4871. */
  4872. pjsua_dtmf_method method;
  4873. /**
  4874. * The signal duration used for the DTMF.
  4875. *
  4876. * Default: PJSUA_CALL_SEND_DTMF_DURATION_DEFAULT
  4877. */
  4878. unsigned duration;
  4879. /**
  4880. * The DTMF digits to be sent.
  4881. */
  4882. pj_str_t digits;
  4883. } pjsua_call_send_dtmf_param;
  4884. /**
  4885. * Initialize call settings.
  4886. *
  4887. * @param opt The call setting to be initialized.
  4888. */
  4889. PJ_DECL(void) pjsua_call_setting_default(pjsua_call_setting *opt);
  4890. /**
  4891. * Initialize video stream operation param with default values.
  4892. *
  4893. * @param param The video stream operation param to be initialized.
  4894. */
  4895. PJ_DECL(void)
  4896. pjsua_call_vid_strm_op_param_default(pjsua_call_vid_strm_op_param *param);
  4897. /**
  4898. * Initialize send DTMF param with default values.
  4899. *
  4900. * @param param The send DTMF param to be initialized.
  4901. */
  4902. PJ_DECL(void)
  4903. pjsua_call_send_dtmf_param_default(pjsua_call_send_dtmf_param *param);
  4904. /**
  4905. * Get maximum number of calls configured in pjsua.
  4906. *
  4907. * @return Maximum number of calls configured.
  4908. */
  4909. PJ_DECL(unsigned) pjsua_call_get_max_count(void);
  4910. /**
  4911. * Get the number of current calls. The number includes active calls
  4912. * (pjsua_call_is_active(call_id) == PJ_TRUE), as well as calls that
  4913. * are no longer active but still in the process of hanging up.
  4914. *
  4915. * @return Number of current calls.
  4916. */
  4917. PJ_DECL(unsigned) pjsua_call_get_count(void);
  4918. /**
  4919. * Enumerate all active calls. Application may then query the information and
  4920. * state of each call by calling #pjsua_call_get_info().
  4921. *
  4922. * @param ids Array of account IDs to be initialized.
  4923. * @param count In input, specifies the maximum number of elements.
  4924. * On return, it contains the actual number of elements.
  4925. *
  4926. * @return PJ_SUCCESS on success, or the appropriate error code.
  4927. */
  4928. PJ_DECL(pj_status_t) pjsua_enum_calls(pjsua_call_id ids[],
  4929. unsigned *count);
  4930. /**
  4931. * Make outgoing call to the specified URI using the specified account.
  4932. *
  4933. * @param acc_id The account to be used.
  4934. * @param dst_uri URI to be put in the To header (normally is the same
  4935. * as the target URI).
  4936. * @param opt Optional call setting. This should be initialized
  4937. * using #pjsua_call_setting_default().
  4938. * @param user_data Arbitrary user data to be attached to the call, and
  4939. * can be retrieved later.
  4940. * @param msg_data Optional headers etc to be added to outgoing INVITE
  4941. * request, or NULL if no custom header is desired.
  4942. * @param p_call_id Pointer to receive call identification.
  4943. *
  4944. * @return PJ_SUCCESS on success, or the appropriate error code.
  4945. */
  4946. PJ_DECL(pj_status_t) pjsua_call_make_call(pjsua_acc_id acc_id,
  4947. const pj_str_t *dst_uri,
  4948. const pjsua_call_setting *opt,
  4949. void *user_data,
  4950. const pjsua_msg_data *msg_data,
  4951. pjsua_call_id *p_call_id);
  4952. /**
  4953. * Check if the specified call has active INVITE session and the INVITE
  4954. * session has not been disconnected.
  4955. *
  4956. * @param call_id Call identification.
  4957. *
  4958. * @return Non-zero if call is active.
  4959. */
  4960. PJ_DECL(pj_bool_t) pjsua_call_is_active(pjsua_call_id call_id);
  4961. /**
  4962. * Check if call has an active media session.
  4963. *
  4964. * @param call_id Call identification.
  4965. *
  4966. * @return Non-zero if yes.
  4967. */
  4968. PJ_DECL(pj_bool_t) pjsua_call_has_media(pjsua_call_id call_id);
  4969. /**
  4970. * Get the conference port identification associated with the call.
  4971. *
  4972. * @param call_id Call identification.
  4973. *
  4974. * @return Conference port ID, or PJSUA_INVALID_ID when the
  4975. * media has not been established or is not active.
  4976. */
  4977. PJ_DECL(pjsua_conf_port_id) pjsua_call_get_conf_port(pjsua_call_id call_id);
  4978. /**
  4979. * Get the video window associated with the call. Note that this function
  4980. * will only evaluate the first video stream in the call, to query any other
  4981. * video stream, use pjsua_call_get_info().
  4982. *
  4983. * @param call_id Call identification.
  4984. *
  4985. * @return Video window, or PJSUA_INVALID_ID when the
  4986. * media has not been established or is not active.
  4987. */
  4988. PJ_DECL(pjsua_vid_win_id) pjsua_call_get_vid_win(pjsua_call_id call_id);
  4989. /**
  4990. * Get the video conference port identification associated with the call.
  4991. * Note that this function will only evaluate the first video stream in
  4992. * the call, to query any other video stream, use pjsua_call_get_info().
  4993. *
  4994. * @param call_id Call identification.
  4995. * @param dir Port direction to be queried. Valid values are
  4996. * PJMEDIA_DIR_ENCODING and PJMEDIA_DIR_DECODING only.
  4997. *
  4998. * @return Conference port ID, or PJSUA_INVALID_ID when the
  4999. * media has not been established or is not active.
  5000. */
  5001. PJ_DECL(pjsua_conf_port_id) pjsua_call_get_vid_conf_port(
  5002. pjsua_call_id call_id,
  5003. pjmedia_dir dir);
  5004. /**
  5005. * Obtain detail information about the specified call.
  5006. *
  5007. * @param call_id Call identification.
  5008. * @param info Call info to be initialized.
  5009. *
  5010. * @return PJ_SUCCESS on success, or the appropriate error code.
  5011. */
  5012. PJ_DECL(pj_status_t) pjsua_call_get_info(pjsua_call_id call_id,
  5013. pjsua_call_info *info);
  5014. /**
  5015. * Check if remote peer support the specified capability.
  5016. *
  5017. * @param call_id Call identification.
  5018. * @param htype The header type to be checked, which value may be:
  5019. * - PJSIP_H_ACCEPT
  5020. * - PJSIP_H_ALLOW
  5021. * - PJSIP_H_SUPPORTED
  5022. * @param hname If htype specifies PJSIP_H_OTHER, then the header
  5023. * name must be supplied in this argument. Otherwise the
  5024. * value must be set to NULL.
  5025. * @param token The capability token to check. For example, if \a
  5026. * htype is PJSIP_H_ALLOW, then \a token specifies the
  5027. * method names; if \a htype is PJSIP_H_SUPPORTED, then
  5028. * \a token specifies the extension names such as
  5029. * "100rel".
  5030. *
  5031. * @return PJSIP_DIALOG_CAP_SUPPORTED if the specified capability
  5032. * is explicitly supported, see pjsip_dialog_cap_status
  5033. * for more info.
  5034. */
  5035. PJ_DECL(pjsip_dialog_cap_status) pjsua_call_remote_has_cap(
  5036. pjsua_call_id call_id,
  5037. int htype,
  5038. const pj_str_t *hname,
  5039. const pj_str_t *token);
  5040. /**
  5041. * Attach application specific data to the call. Application can then
  5042. * inspect this data by calling #pjsua_call_get_user_data().
  5043. *
  5044. * @param call_id Call identification.
  5045. * @param user_data Arbitrary data to be attached to the call.
  5046. *
  5047. * @return The user data.
  5048. */
  5049. PJ_DECL(pj_status_t) pjsua_call_set_user_data(pjsua_call_id call_id,
  5050. void *user_data);
  5051. /**
  5052. * Get user data attached to the call, which has been previously set with
  5053. * #pjsua_call_set_user_data().
  5054. *
  5055. * @param call_id Call identification.
  5056. *
  5057. * @return The user data.
  5058. */
  5059. PJ_DECL(void*) pjsua_call_get_user_data(pjsua_call_id call_id);
  5060. /**
  5061. * Get the NAT type of remote's endpoint. This is a proprietary feature
  5062. * of PJSUA-LIB which sends its NAT type in the SDP when \a nat_type_in_sdp
  5063. * is set in #pjsua_config.
  5064. *
  5065. * This function can only be called after SDP has been received from remote,
  5066. * which means for incoming call, this function can be called as soon as
  5067. * call is received as long as incoming call contains SDP, and for outgoing
  5068. * call, this function can be called only after SDP is received (normally in
  5069. * 200/OK response to INVITE). As a general case, application should call
  5070. * this function after or in \a on_call_media_state() callback.
  5071. *
  5072. * @param call_id Call identification.
  5073. * @param p_type Pointer to store the NAT type. Application can then
  5074. * retrieve the string description of the NAT type
  5075. * by calling pj_stun_get_nat_name().
  5076. *
  5077. * @return PJ_SUCCESS on success.
  5078. *
  5079. * @see pjsua_get_nat_type(), nat_type_in_sdp
  5080. */
  5081. PJ_DECL(pj_status_t) pjsua_call_get_rem_nat_type(pjsua_call_id call_id,
  5082. pj_stun_nat_type *p_type);
  5083. /**
  5084. * Send response to incoming INVITE request. Depending on the status
  5085. * code specified as parameter, this function may send provisional
  5086. * response, establish the call, or terminate the call. See also
  5087. * #pjsua_call_answer2().
  5088. *
  5089. * @param call_id Incoming call identification.
  5090. * @param code Status code, (100-699).
  5091. * @param reason Optional reason phrase. If NULL, default text
  5092. * will be used.
  5093. * @param msg_data Optional list of headers etc to be added to outgoing
  5094. * response message. Note that this message data will
  5095. * be persistent in all next answers/responses for this
  5096. * INVITE request.
  5097. *
  5098. * @return PJ_SUCCESS on success, or the appropriate error code.
  5099. */
  5100. PJ_DECL(pj_status_t) pjsua_call_answer(pjsua_call_id call_id,
  5101. unsigned code,
  5102. const pj_str_t *reason,
  5103. const pjsua_msg_data *msg_data);
  5104. /**
  5105. * Send response to incoming INVITE request with call setting param.
  5106. * Depending on the status code specified as parameter, this function may
  5107. * send provisional response, establish the call, or terminate the call.
  5108. * Notes about call setting:
  5109. * - if call setting is changed in the subsequent call to this function,
  5110. * only the first call setting supplied will applied. So normally
  5111. * application will not supply call setting before getting confirmation
  5112. * from the user.
  5113. * - if no call setting is supplied when SDP has to be sent, i.e: answer
  5114. * with status code 183 or 2xx, the default call setting will be used,
  5115. * check #pjsua_call_setting for its default values.
  5116. *
  5117. * @param call_id Incoming call identification.
  5118. * @param opt Optional call setting.
  5119. * @param code Status code, (100-699).
  5120. * @param reason Optional reason phrase. If NULL, default text
  5121. * will be used.
  5122. * @param msg_data Optional list of headers etc to be added to outgoing
  5123. * response message. Note that this message data will
  5124. * be persistent in all next answers/responses for this
  5125. * INVITE request.
  5126. *
  5127. * @return PJ_SUCCESS on success, or the appropriate error code.
  5128. */
  5129. PJ_DECL(pj_status_t) pjsua_call_answer2(pjsua_call_id call_id,
  5130. const pjsua_call_setting *opt,
  5131. unsigned code,
  5132. const pj_str_t *reason,
  5133. const pjsua_msg_data *msg_data);
  5134. /**
  5135. * Same as #pjsua_call_answer2() but this function will set the SDP
  5136. * answer first before sending the response.
  5137. *
  5138. * @param call_id Incoming call identification.
  5139. * @param sdp SDP answer.
  5140. * @param opt Optional call setting.
  5141. * @param code Status code, (100-699).
  5142. * @param reason Optional reason phrase. If NULL, default text
  5143. * will be used.
  5144. * @param msg_data Optional list of headers etc to be added to outgoing
  5145. * response message. Note that this message data will
  5146. * be persistent in all next answers/responses for this
  5147. * INVITE request.
  5148. *
  5149. * @return PJ_SUCCESS on success, or the appropriate error code.
  5150. */
  5151. PJ_DECL(pj_status_t)
  5152. pjsua_call_answer_with_sdp(pjsua_call_id call_id,
  5153. const pjmedia_sdp_session *sdp,
  5154. const pjsua_call_setting *opt,
  5155. unsigned code,
  5156. const pj_str_t *reason,
  5157. const pjsua_msg_data *msg_data);
  5158. /**
  5159. * Hangup call by using method that is appropriate according to the
  5160. * call state. This function is different than answering the call with
  5161. * 3xx-6xx response (with #pjsua_call_answer()), in that this function
  5162. * will hangup the call regardless of the state and role of the call,
  5163. * while #pjsua_call_answer() only works with incoming calls on EARLY
  5164. * state.
  5165. *
  5166. * After calling this function, media will be deinitialized (call media
  5167. * callbacks, if any, will still be received) and then, on_call_state()
  5168. * will be immediately called with state DISCONNECTED. No further
  5169. * call callbacks will be received after this. The call hangup process
  5170. * itself (sending BYE, waiting for the response, and resource cleanup)
  5171. * will continue in the background and the call slot can be reused only
  5172. * after this process is completed. If application has limited call slots
  5173. * and would like to check if there are any free slots remaining, it can
  5174. * query the number of free slots using the APIs:
  5175. * pjsua_call_get_max_count()-pjsua_call_get_count()
  5176. *
  5177. * Note that on_call_tsx_state() will not be called when using this API.
  5178. *
  5179. * @param call_id Call identification.
  5180. * @param code Optional status code to be sent when we're rejecting
  5181. * incoming call. If the value is zero, "603/Decline"
  5182. * will be sent.
  5183. * @param reason Optional reason phrase to be sent when we're rejecting
  5184. * incoming call. If NULL, default text will be used.
  5185. * @param msg_data Optional list of headers etc to be added to outgoing
  5186. * request/response message.
  5187. *
  5188. * @return PJ_SUCCESS on success, or the appropriate error code.
  5189. */
  5190. PJ_DECL(pj_status_t) pjsua_call_hangup(pjsua_call_id call_id,
  5191. unsigned code,
  5192. const pj_str_t *reason,
  5193. const pjsua_msg_data *msg_data);
  5194. /**
  5195. * Accept or reject redirection response. Application MUST call this function
  5196. * after it signaled PJSIP_REDIRECT_PENDING in the \a on_call_redirected()
  5197. * callback, to notify the call whether to accept or reject the redirection
  5198. * to the current target. Application can use the combination of
  5199. * PJSIP_REDIRECT_PENDING command in \a on_call_redirected() callback and
  5200. * this function to ask for user permission before redirecting the call.
  5201. *
  5202. * Note that if the application chooses to reject or stop redirection (by
  5203. * using PJSIP_REDIRECT_REJECT or PJSIP_REDIRECT_STOP respectively), the
  5204. * call disconnection callback will be called before this function returns.
  5205. * And if the application rejects the target, the \a on_call_redirected()
  5206. * callback may also be called before this function returns if there is
  5207. * another target to try.
  5208. *
  5209. * @param call_id The call ID.
  5210. * @param cmd Redirection operation to be applied to the current
  5211. * target. The semantic of this argument is similar
  5212. * to the description in the \a on_call_redirected()
  5213. * callback, except that the PJSIP_REDIRECT_PENDING is
  5214. * not accepted here.
  5215. *
  5216. * @return PJ_SUCCESS on successful operation.
  5217. */
  5218. PJ_DECL(pj_status_t) pjsua_call_process_redirect(pjsua_call_id call_id,
  5219. pjsip_redirect_op cmd);
  5220. /**
  5221. * Put the specified call on hold. This will send re-INVITE with the
  5222. * appropriate SDP to inform remote that the call is being put on hold.
  5223. * The final status of the request itself will be reported on the
  5224. * \a on_call_media_state() callback, which inform the application that
  5225. * the media state of the call has changed.
  5226. *
  5227. * @param call_id Call identification.
  5228. * @param msg_data Optional message components to be sent with
  5229. * the request.
  5230. *
  5231. * @return PJ_SUCCESS on success, or the appropriate error code.
  5232. */
  5233. PJ_DECL(pj_status_t) pjsua_call_set_hold(pjsua_call_id call_id,
  5234. const pjsua_msg_data *msg_data);
  5235. /**
  5236. * Put the specified call on hold. This will send re-INVITE with the
  5237. * appropriate SDP to inform remote that the call is being put on hold.
  5238. * The final status of the request itself will be reported on the
  5239. * \a on_call_media_state() callback, which inform the application that
  5240. * the media state of the call has changed.
  5241. *
  5242. * @param call_id Call identification.
  5243. * @param options Bitmask of pjsua_call_flag constants. Currently, only
  5244. * the flag PJSUA_CALL_UPDATE_CONTACT can be used.
  5245. * @param msg_data Optional message components to be sent with
  5246. * the request.
  5247. *
  5248. * @return PJ_SUCCESS on success, or the appropriate error code.
  5249. */
  5250. PJ_DECL(pj_status_t) pjsua_call_set_hold2(pjsua_call_id call_id,
  5251. unsigned options,
  5252. const pjsua_msg_data *msg_data);
  5253. /**
  5254. * Send re-INVITE request or release hold.
  5255. * The final status of the request itself will be reported on the
  5256. * \a on_call_media_state() callback, which inform the application that
  5257. * the media state of the call has changed.
  5258. *
  5259. * @param call_id Call identification.
  5260. * @param options Bitmask of pjsua_call_flag constants. Note that
  5261. * for compatibility, specifying PJ_TRUE here is
  5262. * equal to specifying PJSUA_CALL_UNHOLD flag.
  5263. * @param msg_data Optional message components to be sent with
  5264. * the request.
  5265. *
  5266. * @return PJ_SUCCESS on success, or the appropriate error code.
  5267. */
  5268. PJ_DECL(pj_status_t) pjsua_call_reinvite(pjsua_call_id call_id,
  5269. unsigned options,
  5270. const pjsua_msg_data *msg_data);
  5271. /**
  5272. * Send re-INVITE request or release hold.
  5273. * The final status of the request itself will be reported on the
  5274. * \a on_call_media_state() callback, which inform the application that
  5275. * the media state of the call has changed.
  5276. *
  5277. * @param call_id Call identification.
  5278. * @param opt Optional call setting, if NULL, the current call
  5279. * setting will be used. Note that to release hold
  5280. * or update contact or omit SDP offer, this parameter
  5281. * cannot be NULL and it must specify appropriate flags,
  5282. * e.g: PJSUA_CALL_UNHOLD, PJSUA_CALL_UPDATE_CONTACT,
  5283. * PJSUA_CALL_NO_SDP_OFFER.
  5284. * @param msg_data Optional message components to be sent with
  5285. * the request.
  5286. *
  5287. * @return PJ_SUCCESS on success, or the appropriate error code.
  5288. */
  5289. PJ_DECL(pj_status_t) pjsua_call_reinvite2(pjsua_call_id call_id,
  5290. const pjsua_call_setting *opt,
  5291. const pjsua_msg_data *msg_data);
  5292. /**
  5293. * Send UPDATE request.
  5294. *
  5295. * @param call_id Call identification.
  5296. * @param options Bitmask of pjsua_call_flag constants.
  5297. * @param msg_data Optional message components to be sent with
  5298. * the request.
  5299. *
  5300. * @return PJ_SUCCESS on success, or the appropriate error code.
  5301. */
  5302. PJ_DECL(pj_status_t) pjsua_call_update(pjsua_call_id call_id,
  5303. unsigned options,
  5304. const pjsua_msg_data *msg_data);
  5305. /**
  5306. * Send UPDATE request.
  5307. *
  5308. * @param call_id Call identification.
  5309. * @param opt Optional call setting, if NULL, the current call
  5310. * setting will be used. Note that to release hold
  5311. * or update contact or omit SDP offer, this parameter
  5312. * cannot be NULL and it must specify appropriate flags,
  5313. * e.g: PJSUA_CALL_UNHOLD, PJSUA_CALL_UPDATE_CONTACT,
  5314. * PJSUA_CALL_NO_SDP_OFFER.
  5315. * @param msg_data Optional message components to be sent with
  5316. * the request.
  5317. *
  5318. * @return PJ_SUCCESS on success, or the appropriate error code.
  5319. */
  5320. PJ_DECL(pj_status_t) pjsua_call_update2(pjsua_call_id call_id,
  5321. const pjsua_call_setting *opt,
  5322. const pjsua_msg_data *msg_data);
  5323. /**
  5324. * Initiate call transfer to the specified address. This function will send
  5325. * REFER request to instruct remote call party to initiate a new INVITE
  5326. * session to the specified destination/target.
  5327. *
  5328. * If application is interested to monitor the successfulness and
  5329. * the progress of the transfer request, it can implement
  5330. * \a on_call_transfer_status() callback which will report the progress
  5331. * of the call transfer request.
  5332. *
  5333. * @param call_id The call id to be transferred.
  5334. * @param dest URI of new target to be contacted. The URI may be
  5335. * in name address or addr-spec format.
  5336. * @param msg_data Optional message components to be sent with
  5337. * the request.
  5338. *
  5339. * @return PJ_SUCCESS on success, or the appropriate error code.
  5340. */
  5341. PJ_DECL(pj_status_t) pjsua_call_xfer(pjsua_call_id call_id,
  5342. const pj_str_t *dest,
  5343. const pjsua_msg_data *msg_data);
  5344. /**
  5345. * Flag to indicate that "Require: replaces" should not be put in the
  5346. * outgoing INVITE request caused by REFER request created by
  5347. * #pjsua_call_xfer_replaces().
  5348. */
  5349. #define PJSUA_XFER_NO_REQUIRE_REPLACES 1
  5350. /**
  5351. * Initiate attended call transfer. This function will send REFER request
  5352. * to instruct remote call party to initiate new INVITE session to the URL
  5353. * of \a dest_call_id. The party at \a dest_call_id then should "replace"
  5354. * the call with us with the new call from the REFER recipient.
  5355. *
  5356. * @param call_id The call id to be transferred.
  5357. * @param dest_call_id The call id to be replaced.
  5358. * @param options Application may specify PJSUA_XFER_NO_REQUIRE_REPLACES
  5359. * to suppress the inclusion of "Require: replaces" in
  5360. * the outgoing INVITE request created by the REFER
  5361. * request.
  5362. * @param msg_data Optional message components to be sent with
  5363. * the request.
  5364. *
  5365. * @return PJ_SUCCESS on success, or the appropriate error code.
  5366. */
  5367. PJ_DECL(pj_status_t) pjsua_call_xfer_replaces(pjsua_call_id call_id,
  5368. pjsua_call_id dest_call_id,
  5369. unsigned options,
  5370. const pjsua_msg_data *msg_data);
  5371. /**
  5372. * Send DTMF digits to remote using RFC 2833 payload formats. Use
  5373. * #pjsua_call_send_dtmf() to send DTMF using SIP INFO or other method in
  5374. * \a pjsua_dtmf_method. App can use \a on_dtmf_digit() or \a on_dtmf_digit2()
  5375. * callback to monitor incoming DTMF.
  5376. *
  5377. * @param call_id Call identification.
  5378. * @param digits DTMF string digits to be sent as described on RFC 2833
  5379. * section 3.10. If PJMEDIA_HAS_DTMF_FLASH is enabled,
  5380. * character 'R' is used to represent the
  5381. * event type 16 (flash) as stated in RFC 4730.
  5382. *
  5383. * @return PJ_SUCCESS on success, or the appropriate error code.
  5384. */
  5385. PJ_DECL(pj_status_t) pjsua_call_dial_dtmf(pjsua_call_id call_id,
  5386. const pj_str_t *digits);
  5387. /**
  5388. * Send DTMF digits to remote. Use this method to send DTMF using the method in
  5389. * \a pjsua_dtmf_method. This method will call #pjsua_call_dial_dtmf() when
  5390. * sending DTMF using \a PJSUA_DTMF_METHOD_RFC2833. Note that
  5391. * \a on_dtmf_digit() callback can only monitor incoming DTMF using RFC 2833.
  5392. * App can use \a on_dtmf_digit2() to monitor incoming DTMF using the method in
  5393. * \a pjsua_dtmf_method. Note that \a on_dtmf_digit() will not be called once
  5394. * \a on_dtmf_digit2() is implemented.
  5395. *
  5396. * @param call_id Call identification.
  5397. * @param param The send DTMF parameter.
  5398. *
  5399. * @return PJ_SUCCESS on success, or the appropriate error code.
  5400. */
  5401. PJ_DECL(pj_status_t) pjsua_call_send_dtmf(pjsua_call_id call_id,
  5402. const pjsua_call_send_dtmf_param *param);
  5403. /**
  5404. * Send instant messaging inside INVITE session.
  5405. *
  5406. * @param call_id Call identification.
  5407. * @param mime_type Optional MIME type. If NULL, then "text/plain" is
  5408. * assumed.
  5409. * @param content The message content. Can be NULL if msg_data specifies
  5410. * body and/or multipart.
  5411. * @param msg_data Optional list of headers etc to be included in outgoing
  5412. * request. The body descriptor in the msg_data is
  5413. * ignored if parameter 'content' is set.
  5414. * @param user_data Optional user data, which will be given back when
  5415. * the IM callback is called.
  5416. *
  5417. * @return PJ_SUCCESS on success, or the appropriate error code.
  5418. */
  5419. PJ_DECL(pj_status_t) pjsua_call_send_im( pjsua_call_id call_id,
  5420. const pj_str_t *mime_type,
  5421. const pj_str_t *content,
  5422. const pjsua_msg_data *msg_data,
  5423. void *user_data);
  5424. /**
  5425. * Send IM typing indication inside INVITE session.
  5426. *
  5427. * @param call_id Call identification.
  5428. * @param is_typing Non-zero to indicate to remote that local person is
  5429. * currently typing an IM.
  5430. * @param msg_data Optional list of headers etc to be included in outgoing
  5431. * request.
  5432. *
  5433. * @return PJ_SUCCESS on success, or the appropriate error code.
  5434. */
  5435. PJ_DECL(pj_status_t) pjsua_call_send_typing_ind(pjsua_call_id call_id,
  5436. pj_bool_t is_typing,
  5437. const pjsua_msg_data*msg_data);
  5438. /**
  5439. * Send arbitrary request with the call. This is useful for example to send
  5440. * INFO request. Note that application should not use this function to send
  5441. * requests which would change the invite session's state, such as re-INVITE,
  5442. * UPDATE, PRACK, and BYE.
  5443. *
  5444. * @param call_id Call identification.
  5445. * @param method SIP method of the request.
  5446. * @param msg_data Optional message body and/or list of headers to be
  5447. * included in outgoing request.
  5448. *
  5449. * @return PJ_SUCCESS on success, or the appropriate error code.
  5450. */
  5451. PJ_DECL(pj_status_t) pjsua_call_send_request(pjsua_call_id call_id,
  5452. const pj_str_t *method,
  5453. const pjsua_msg_data *msg_data);
  5454. /**
  5455. * Terminate all calls. This will initiate #pjsua_call_hangup() for all
  5456. * currently active calls.
  5457. */
  5458. PJ_DECL(void) pjsua_call_hangup_all(void);
  5459. /**
  5460. * Dump call and media statistics to string.
  5461. *
  5462. * @param call_id Call identification.
  5463. * @param with_media Non-zero to include media information too.
  5464. * @param buffer Buffer where the statistics are to be written to.
  5465. * @param maxlen Maximum length of buffer.
  5466. * @param indent Spaces for left indentation.
  5467. *
  5468. * @return PJ_SUCCESS on success.
  5469. */
  5470. PJ_DECL(pj_status_t) pjsua_call_dump(pjsua_call_id call_id,
  5471. pj_bool_t with_media,
  5472. char *buffer,
  5473. unsigned maxlen,
  5474. const char *indent);
  5475. /**
  5476. * Get the media stream index of the default video stream in the call.
  5477. * Typically this will just retrieve the stream index of the first
  5478. * activated video stream in the call. If none is active, it will return
  5479. * the first inactive video stream.
  5480. *
  5481. * @param call_id Call identification.
  5482. *
  5483. * @return The media stream index or -1 if no video stream
  5484. * is present in the call.
  5485. */
  5486. PJ_DECL(int) pjsua_call_get_vid_stream_idx(pjsua_call_id call_id);
  5487. /**
  5488. * Determine if video stream for the specified call is currently running
  5489. * (i.e. has been created, started, and not being paused) for the specified
  5490. * direction.
  5491. *
  5492. * @param call_id Call identification.
  5493. * @param med_idx Media stream index, or -1 to specify default video
  5494. * media.
  5495. * @param dir The direction to be checked.
  5496. *
  5497. * @return PJ_TRUE if stream is currently running for the
  5498. * specified direction.
  5499. */
  5500. PJ_DECL(pj_bool_t) pjsua_call_vid_stream_is_running(pjsua_call_id call_id,
  5501. int med_idx,
  5502. pjmedia_dir dir);
  5503. /**
  5504. * Add, remove, modify, and/or manipulate video media stream for the
  5505. * specified call. This may trigger a re-INVITE or UPDATE to be sent
  5506. * for the call.
  5507. *
  5508. * @param call_id Call identification.
  5509. * @param op The video stream operation to be performed,
  5510. * possible values are #pjsua_call_vid_strm_op.
  5511. * @param param The parameters for the video stream operation,
  5512. * or NULL for the default parameter values
  5513. * (see #pjsua_call_vid_strm_op_param).
  5514. *
  5515. * @return PJ_SUCCESS on success or the appropriate error.
  5516. */
  5517. PJ_DECL(pj_status_t) pjsua_call_set_vid_strm (
  5518. pjsua_call_id call_id,
  5519. pjsua_call_vid_strm_op op,
  5520. const pjsua_call_vid_strm_op_param *param);
  5521. /**
  5522. * Modify the video stream's codec parameter after the codec is opened.
  5523. * Note that not all codec backends support modifying parameters during
  5524. * runtime and only certain parameters can be changed.
  5525. *
  5526. * Currently, only Video Toolbox and OpenH264 backends support runtime
  5527. * adjustment of encoding bitrate (avg_bps and max_bps).
  5528. *
  5529. * @param call_id Call identification.
  5530. * @param med_idx Video stream index.
  5531. * @param param The new codec parameter.
  5532. *
  5533. * @return PJ_SUCCESS on success.
  5534. */
  5535. PJ_DECL(pj_status_t)
  5536. pjsua_call_vid_stream_modify_codec_param(pjsua_call_id call_id,
  5537. int med_idx,
  5538. const pjmedia_vid_codec_param *param);
  5539. /**
  5540. * Modify the audio stream's codec parameter after the codec is opened.
  5541. * Note that not all codec parameters can be modified during run-time.
  5542. * Currently, only Opus codec supports changing key codec parameters
  5543. * such as bitrate and bandwidth, while other codecs may only be able to
  5544. * modify minor settings such as VAD or PLC.
  5545. *
  5546. * @param call_id Call identification.
  5547. * @param med_idx Media stream index, or -1 to specify default audio
  5548. * media.
  5549. * @param param The new codec parameter.
  5550. *
  5551. * @return PJ_SUCCESS on success.
  5552. */
  5553. PJ_DECL(pj_status_t)
  5554. pjsua_call_aud_stream_modify_codec_param(pjsua_call_id call_id,
  5555. int med_idx,
  5556. const pjmedia_codec_param *param);
  5557. /**
  5558. * Get media stream info for the specified media index.
  5559. *
  5560. * @param call_id The call identification.
  5561. * @param med_idx Media stream index.
  5562. * @param psi To be filled with the stream info.
  5563. *
  5564. * @return PJ_SUCCESS on success or the appropriate error.
  5565. */
  5566. PJ_DECL(pj_status_t) pjsua_call_get_stream_info(pjsua_call_id call_id,
  5567. unsigned med_idx,
  5568. pjsua_stream_info *psi);
  5569. /**
  5570. * Get media stream statistic for the specified media index.
  5571. *
  5572. * @param call_id The call identification.
  5573. * @param med_idx Media stream index.
  5574. * @param stat To be filled with the stream statistic.
  5575. *
  5576. * @return PJ_SUCCESS on success or the appropriate error.
  5577. */
  5578. PJ_DECL(pj_status_t) pjsua_call_get_stream_stat(pjsua_call_id call_id,
  5579. unsigned med_idx,
  5580. pjsua_stream_stat *stat);
  5581. /**
  5582. * Get media transport info for the specified media index.
  5583. *
  5584. * @param call_id The call identification.
  5585. * @param med_idx Media stream index.
  5586. * @param t To be filled with the transport info.
  5587. *
  5588. * @return PJ_SUCCESS on success or the appropriate error.
  5589. */
  5590. PJ_DECL(pj_status_t)
  5591. pjsua_call_get_med_transport_info(pjsua_call_id call_id,
  5592. unsigned med_idx,
  5593. pjmedia_transport_info *t);
  5594. /**
  5595. * @}
  5596. */
  5597. /*****************************************************************************
  5598. * BUDDY API
  5599. */
  5600. /**
  5601. * @defgroup PJSUA_LIB_BUDDY PJSUA-API Buddy, Presence, and Instant Messaging
  5602. * @ingroup PJSUA_LIB
  5603. * @brief Buddy management, buddy's presence, and instant messaging.
  5604. * @{
  5605. *
  5606. * This section describes PJSUA-APIs related to buddies management,
  5607. * presence management, and instant messaging.
  5608. */
  5609. /**
  5610. * Max buddies in buddy list.
  5611. */
  5612. #ifndef PJSUA_MAX_BUDDIES
  5613. # define PJSUA_MAX_BUDDIES 256
  5614. #endif
  5615. /**
  5616. * This specifies how long the library should wait before retrying failed
  5617. * SUBSCRIBE request, and there is no rule to automatically resubscribe
  5618. * (for example, no "retry-after" parameter in Subscription-State header).
  5619. *
  5620. * This also controls the duration before failed PUBLISH request will be
  5621. * retried.
  5622. *
  5623. * Default: 300 seconds
  5624. */
  5625. #ifndef PJSUA_PRES_TIMER
  5626. # define PJSUA_PRES_TIMER 300
  5627. #endif
  5628. /**
  5629. * This specifies the buffer size of pjsua_buddy_dlg_event_info.
  5630. *
  5631. * Default: 1024 bytes
  5632. */
  5633. #ifndef PJSUA_BUDDY_DLG_EVENT_INFO_BUF_SIZE
  5634. # define PJSUA_BUDDY_DLG_EVENT_INFO_BUF_SIZE 1024
  5635. #endif
  5636. /**
  5637. * This structure describes buddy configuration when adding a buddy to
  5638. * the buddy list with #pjsua_buddy_add(). Application MUST initialize
  5639. * the structure with #pjsua_buddy_config_default() to initialize this
  5640. * structure with default configuration.
  5641. */
  5642. typedef struct pjsua_buddy_config
  5643. {
  5644. /**
  5645. * Buddy URL or name address.
  5646. */
  5647. pj_str_t uri;
  5648. /**
  5649. * Specify whether presence subscription should start immediately.
  5650. * Note that only one subscription (presence or dialog event)
  5651. * can be active at any time.
  5652. */
  5653. pj_bool_t subscribe;
  5654. /**
  5655. * Specify whether we should immediately subscribe to the buddy's
  5656. * dialog event, such as for Busy Lamp Field (BLF) feature.
  5657. * Note that only one subscription (presence or dialog event)
  5658. * can be active at any time.
  5659. */
  5660. pj_bool_t subscribe_dlg_event;
  5661. /**
  5662. * Specify arbitrary application data to be associated with with
  5663. * the buddy object.
  5664. */
  5665. void *user_data;
  5666. } pjsua_buddy_config;
  5667. /**
  5668. * This enumeration describes basic buddy's online status.
  5669. */
  5670. typedef enum pjsua_buddy_status
  5671. {
  5672. /**
  5673. * Online status is unknown (possibly because no presence subscription
  5674. * has been established).
  5675. */
  5676. PJSUA_BUDDY_STATUS_UNKNOWN,
  5677. /**
  5678. * Buddy is known to be online.
  5679. */
  5680. PJSUA_BUDDY_STATUS_ONLINE,
  5681. /**
  5682. * Buddy is offline.
  5683. */
  5684. PJSUA_BUDDY_STATUS_OFFLINE,
  5685. } pjsua_buddy_status;
  5686. /**
  5687. * This structure describes buddy info, which can be retrieved by calling
  5688. * #pjsua_buddy_get_info().
  5689. */
  5690. typedef struct pjsua_buddy_info
  5691. {
  5692. /**
  5693. * The buddy ID.
  5694. */
  5695. pjsua_buddy_id id;
  5696. /**
  5697. * The full URI of the buddy, as specified in the configuration.
  5698. */
  5699. pj_str_t uri;
  5700. /**
  5701. * Buddy's Contact, only available when presence subscription has
  5702. * been established to the buddy.
  5703. */
  5704. pj_str_t contact;
  5705. /**
  5706. * Buddy's online status.
  5707. */
  5708. pjsua_buddy_status status;
  5709. /**
  5710. * Text to describe buddy's online status.
  5711. */
  5712. pj_str_t status_text;
  5713. /**
  5714. * Flag to indicate that we should monitor the presence information for
  5715. * this buddy (normally yes, unless explicitly disabled).
  5716. */
  5717. pj_bool_t monitor_pres;
  5718. /**
  5719. * If \a monitor_pres is enabled, this specifies the last state of the
  5720. * presence subscription. If presence subscription session is currently
  5721. * active, the value will be PJSIP_EVSUB_STATE_ACTIVE. If presence
  5722. * subscription request has been rejected, the value will be
  5723. * PJSIP_EVSUB_STATE_TERMINATED, and the termination reason will be
  5724. * specified in \a sub_term_reason.
  5725. */
  5726. pjsip_evsub_state sub_state;
  5727. /**
  5728. * String representation of subscription state.
  5729. */
  5730. const char *sub_state_name;
  5731. /**
  5732. * Specifies the last presence subscription termination code. This would
  5733. * return the last status of the SUBSCRIBE request. If the subscription
  5734. * is terminated with NOTIFY by the server, this value will be set to
  5735. * 200, and subscription termination reason will be given in the
  5736. * \a sub_term_reason field.
  5737. */
  5738. unsigned sub_term_code;
  5739. /**
  5740. * Specifies the last presence subscription termination reason. If
  5741. * presence subscription is currently active, the value will be empty.
  5742. */
  5743. pj_str_t sub_term_reason;
  5744. /**
  5745. * Extended RPID information about the person.
  5746. */
  5747. pjrpid_element rpid;
  5748. /**
  5749. * Extended presence info.
  5750. */
  5751. pjsip_pres_status pres_status;
  5752. /**
  5753. * Internal buffer.
  5754. */
  5755. char buf_[512];
  5756. } pjsua_buddy_info;
  5757. typedef struct pjsua_buddy_dlg_event_info
  5758. {
  5759. /**
  5760. * The buddy ID.
  5761. */
  5762. pjsua_buddy_id id;
  5763. /**
  5764. * The full URI of the buddy, as specified in the configuration.
  5765. */
  5766. pj_str_t uri;
  5767. /* Dialog event Dialog-Info id */
  5768. pj_str_t dialog_id;
  5769. /* Dialog event Dialog-Info state */
  5770. pj_str_t dialog_info_state;
  5771. /* Dialog event Dialog-Info entity */
  5772. pj_str_t dialog_info_entity;
  5773. /* Dialog event Dialog call_id */
  5774. pj_str_t dialog_call_id;
  5775. /* Dialog event Dialog remote_tag */
  5776. pj_str_t dialog_remote_tag;
  5777. /* Dialog event Dialog local_tag */
  5778. pj_str_t dialog_local_tag;
  5779. /* Dialog event Dialog direction */
  5780. pj_str_t dialog_direction;
  5781. /* Dialog event dialog state */
  5782. pj_str_t dialog_state;
  5783. /* Dialog event dialog duration */
  5784. pj_str_t dialog_duration;
  5785. /* Dialog event local identity */
  5786. pj_str_t local_identity;
  5787. /* Dialog event local identity_display */
  5788. pj_str_t local_identity_display;
  5789. /* Dialog event local target uri */
  5790. pj_str_t local_target_uri;
  5791. /* Dialog event remote identity */
  5792. pj_str_t remote_identity;
  5793. /* Dialog event remote identity_display */
  5794. pj_str_t remote_identity_display;
  5795. /* Dialog event remote target uri */
  5796. pj_str_t remote_target_uri;
  5797. /**
  5798. * This specifies the last state of the dialog event subscription.
  5799. */
  5800. pjsip_evsub_state sub_state;
  5801. /**
  5802. * String representation of subscription state.
  5803. */
  5804. const char *sub_state_name;
  5805. /**
  5806. * Specifies the last dialog event subscription termination code.
  5807. */
  5808. unsigned sub_term_code;
  5809. /**
  5810. * Specifies the last dialog event subscription termination reason. If
  5811. * presence subscription is currently active, the value will be empty.
  5812. */
  5813. pj_str_t sub_term_reason;
  5814. /**
  5815. * Internal buffer.
  5816. */
  5817. char buf_[PJSUA_BUDDY_DLG_EVENT_INFO_BUF_SIZE];
  5818. } pjsua_buddy_dlg_event_info;
  5819. /**
  5820. * Set default values to the buddy config.
  5821. */
  5822. PJ_DECL(void) pjsua_buddy_config_default(pjsua_buddy_config *cfg);
  5823. /**
  5824. * Get total number of buddies.
  5825. *
  5826. * @return Number of buddies.
  5827. */
  5828. PJ_DECL(unsigned) pjsua_get_buddy_count(void);
  5829. /**
  5830. * Check if buddy ID is valid.
  5831. *
  5832. * @param buddy_id Buddy ID to check.
  5833. *
  5834. * @return Non-zero if buddy ID is valid.
  5835. */
  5836. PJ_DECL(pj_bool_t) pjsua_buddy_is_valid(pjsua_buddy_id buddy_id);
  5837. /**
  5838. * Enumerate all buddy IDs in the buddy list. Application then can use
  5839. * #pjsua_buddy_get_info() to get the detail information for each buddy
  5840. * id.
  5841. *
  5842. * @param ids Array of ids to be initialized.
  5843. * @param count On input, specifies max elements in the array.
  5844. * On return, it contains actual number of elements
  5845. * that have been initialized.
  5846. *
  5847. * @return PJ_SUCCESS on success, or the appropriate error code.
  5848. */
  5849. PJ_DECL(pj_status_t) pjsua_enum_buddies(pjsua_buddy_id ids[],
  5850. unsigned *count);
  5851. /**
  5852. * Find the buddy ID with the specified URI.
  5853. *
  5854. * @param uri The buddy URI.
  5855. *
  5856. * @return The buddy ID, or PJSUA_INVALID_ID if not found.
  5857. */
  5858. PJ_DECL(pjsua_buddy_id) pjsua_buddy_find(const pj_str_t *uri);
  5859. /**
  5860. * Get detailed buddy info.
  5861. *
  5862. * @param buddy_id The buddy identification.
  5863. * @param info Pointer to receive information about buddy.
  5864. *
  5865. * @return PJ_SUCCESS on success, or the appropriate error code.
  5866. */
  5867. PJ_DECL(pj_status_t) pjsua_buddy_get_info(pjsua_buddy_id buddy_id,
  5868. pjsua_buddy_info *info);
  5869. /**
  5870. * Get detailed buddy dialog event info.
  5871. *
  5872. * @param buddy_id The buddy identification.
  5873. * @param info Pointer to receive information about buddy.
  5874. *
  5875. * @return PJ_SUCCESS on success, or the appropriate error code.
  5876. */
  5877. PJ_DECL(pj_status_t)
  5878. pjsua_buddy_get_dlg_event_info(pjsua_buddy_id buddy_id,
  5879. pjsua_buddy_dlg_event_info *info);
  5880. /**
  5881. * Set the user data associated with the buddy object.
  5882. *
  5883. * @param buddy_id The buddy identification.
  5884. * @param user_data Arbitrary application data to be associated with
  5885. * the buddy object.
  5886. *
  5887. * @return PJ_SUCCESS on success, or the appropriate error code.
  5888. */
  5889. PJ_DECL(pj_status_t) pjsua_buddy_set_user_data(pjsua_buddy_id buddy_id,
  5890. void *user_data);
  5891. /**
  5892. * Get the user data associated with the budy object.
  5893. *
  5894. * @param buddy_id The buddy identification.
  5895. *
  5896. * @return The application data.
  5897. */
  5898. PJ_DECL(void*) pjsua_buddy_get_user_data(pjsua_buddy_id buddy_id);
  5899. /**
  5900. * Add new buddy to the buddy list. If presence subscription is enabled
  5901. * for this buddy, this function will also start the presence subscription
  5902. * session immediately.
  5903. *
  5904. * @param buddy_cfg Buddy configuration.
  5905. * @param p_buddy_id Pointer to receive buddy ID.
  5906. *
  5907. * @return PJ_SUCCESS on success, or the appropriate error code.
  5908. */
  5909. PJ_DECL(pj_status_t) pjsua_buddy_add(const pjsua_buddy_config *buddy_cfg,
  5910. pjsua_buddy_id *p_buddy_id);
  5911. /**
  5912. * Delete the specified buddy from the buddy list. Any presence subscription
  5913. * to this buddy will be terminated.
  5914. *
  5915. * @param buddy_id Buddy identification.
  5916. *
  5917. * @return PJ_SUCCESS on success, or the appropriate error code.
  5918. */
  5919. PJ_DECL(pj_status_t) pjsua_buddy_del(pjsua_buddy_id buddy_id);
  5920. /**
  5921. * Enable/disable buddy's presence monitoring. Once buddy's presence is
  5922. * subscribed, application will be informed about buddy's presence status
  5923. * changed via \a on_buddy_state() callback.
  5924. *
  5925. * Note that only one subscription (presence or dialog event) can be active
  5926. * at any time.
  5927. *
  5928. * @param buddy_id Buddy identification.
  5929. * @param subscribe Specify non-zero to activate presence subscription to
  5930. * the specified buddy.
  5931. *
  5932. * @return PJ_SUCCESS on success, or the appropriate error code.
  5933. */
  5934. PJ_DECL(pj_status_t) pjsua_buddy_subscribe_pres(pjsua_buddy_id buddy_id,
  5935. pj_bool_t subscribe);
  5936. /**
  5937. * Enable/disable buddy's dialog event monitoring. Once buddy's dialog event
  5938. * is subscribed, application will be informed about buddy's dialog info
  5939. * status change via \a on_buddy_dlg_event_state() callback.
  5940. *
  5941. * Note that only one subscription (presence or dialog event) can be active
  5942. * at any time.
  5943. *
  5944. * @param buddy_id Buddy identification.
  5945. * @param subscribe Specify non-zero to activate dialog event subscription
  5946. * to the specified buddy.
  5947. *
  5948. * @return PJ_SUCCESS on success, or the appropriate error code.
  5949. */
  5950. PJ_DECL(pj_status_t) pjsua_buddy_subscribe_dlg_event(pjsua_buddy_id buddy_id,
  5951. pj_bool_t subscribe);
  5952. /**
  5953. * Update the presence information for the buddy. Although the library
  5954. * periodically refreshes the presence subscription for all buddies, some
  5955. * application may want to refresh the buddy's presence subscription
  5956. * immediately, and in this case it can use this function to accomplish
  5957. * this.
  5958. *
  5959. * Note that the buddy's presence subscription will only be initiated
  5960. * if presence monitoring is enabled for the buddy. See
  5961. * #pjsua_buddy_subscribe_pres() for more info. Also if presence subscription
  5962. * for the buddy is already active, this function will not do anything.
  5963. *
  5964. * Once the presence subscription is activated successfully for the buddy,
  5965. * application will be notified about the buddy's presence status in the
  5966. * on_buddy_state() callback.
  5967. *
  5968. * @param buddy_id Buddy identification.
  5969. *
  5970. * @return PJ_SUCCESS on success, or the appropriate error code.
  5971. */
  5972. PJ_DECL(pj_status_t) pjsua_buddy_update_pres(pjsua_buddy_id buddy_id);
  5973. /**
  5974. * Update the dialog event information for the buddy. Although the library
  5975. * periodically refreshes the dialog event subscription for all buddies, some
  5976. * application may want to refresh the buddy's dialog event subscription
  5977. * immediately, and in this case it can use this function to accomplish
  5978. * this.
  5979. *
  5980. * Note that the buddy's dialog event subscription will only be initiated
  5981. * if dialog event monitoring is enabled for the buddy. See
  5982. * #pjsua_buddy_subscribe_dlg_event() for more info. Also if dialog event
  5983. * subscription for the buddy is already active, this function will not do
  5984. * anything.
  5985. *
  5986. * Once the dialog event subscription is activated successfully for the buddy,
  5987. * application will be notified about the buddy's dialog info status in the
  5988. * on_buddy_dlg_event_state() callback.
  5989. *
  5990. * @param buddy_id Buddy identification.
  5991. *
  5992. * @return PJ_SUCCESS on success, or the appropriate error code.
  5993. */
  5994. PJ_DECL(pj_status_t) pjsua_buddy_update_dlg_event(pjsua_buddy_id buddy_id);
  5995. /**
  5996. * Send NOTIFY to inform account presence status or to terminate server
  5997. * side presence subscription. If application wants to reject the incoming
  5998. * request, it should set the \a state to PJSIP_EVSUB_STATE_TERMINATED.
  5999. *
  6000. * @param acc_id Account ID.
  6001. * @param srv_pres Server presence subscription instance.
  6002. * @param state New state to set.
  6003. * @param state_str Optionally specify the state string name, if state
  6004. * is not "active", "pending", or "terminated".
  6005. * @param reason If the new state is PJSIP_EVSUB_STATE_TERMINATED,
  6006. * optionally specify the termination reason.
  6007. * @param with_body If the new state is PJSIP_EVSUB_STATE_TERMINATED,
  6008. * this specifies whether the NOTIFY request should
  6009. * contain message body containing account's presence
  6010. * information.
  6011. * @param msg_data Optional list of headers to be sent with the NOTIFY
  6012. * request.
  6013. *
  6014. * @return PJ_SUCCESS on success.
  6015. */
  6016. PJ_DECL(pj_status_t) pjsua_pres_notify(pjsua_acc_id acc_id,
  6017. pjsua_srv_pres *srv_pres,
  6018. pjsip_evsub_state state,
  6019. const pj_str_t *state_str,
  6020. const pj_str_t *reason,
  6021. pj_bool_t with_body,
  6022. const pjsua_msg_data *msg_data);
  6023. /**
  6024. * Dump presence subscriptions to log.
  6025. *
  6026. * @param verbose Yes or no.
  6027. */
  6028. PJ_DECL(void) pjsua_pres_dump(pj_bool_t verbose);
  6029. /**
  6030. * The MESSAGE method (defined in pjsua_im.c)
  6031. */
  6032. extern const pjsip_method pjsip_message_method;
  6033. /**
  6034. * The INFO method (defined in pjsua_call.c)
  6035. */
  6036. extern const pjsip_method pjsip_info_method;
  6037. /**
  6038. * Send instant messaging outside dialog, using the specified account for
  6039. * route set and authentication.
  6040. *
  6041. * @param acc_id Account ID to be used to send the request.
  6042. * @param to Remote URI.
  6043. * @param mime_type Optional MIME type. If NULL, then "text/plain" is
  6044. * assumed.
  6045. * @param content The message content. Can be NULL if msg_data specifies
  6046. * body and/or multipart.
  6047. * @param msg_data Optional list of headers etc to be included in outgoing
  6048. * request. The body descriptor in the msg_data is
  6049. * ignored if parameter 'content' is set.
  6050. * @param user_data Optional user data, which will be given back when
  6051. * the IM callback is called.
  6052. *
  6053. * @return PJ_SUCCESS on success, or the appropriate error code.
  6054. */
  6055. PJ_DECL(pj_status_t) pjsua_im_send(pjsua_acc_id acc_id,
  6056. const pj_str_t *to,
  6057. const pj_str_t *mime_type,
  6058. const pj_str_t *content,
  6059. const pjsua_msg_data *msg_data,
  6060. void *user_data);
  6061. /**
  6062. * Send typing indication outside dialog.
  6063. *
  6064. * @param acc_id Account ID to be used to send the request.
  6065. * @param to Remote URI.
  6066. * @param is_typing If non-zero, it tells remote person that local person
  6067. * is currently composing an IM.
  6068. * @param msg_data Optional list of headers etc to be added to outgoing
  6069. * request.
  6070. *
  6071. * @return PJ_SUCCESS on success, or the appropriate error code.
  6072. */
  6073. PJ_DECL(pj_status_t) pjsua_im_typing(pjsua_acc_id acc_id,
  6074. const pj_str_t *to,
  6075. pj_bool_t is_typing,
  6076. const pjsua_msg_data *msg_data);
  6077. /**
  6078. * @}
  6079. */
  6080. /*****************************************************************************
  6081. * MEDIA API
  6082. */
  6083. /**
  6084. * @defgroup PJSUA_LIB_MEDIA PJSUA-API Media Manipulation
  6085. * @ingroup PJSUA_LIB
  6086. * @brief Media manipulation.
  6087. * @{
  6088. *
  6089. * PJSUA has rather powerful media features, which are built around the
  6090. * PJMEDIA conference bridge. Basically, all media "ports" (such as calls, WAV
  6091. * players, WAV playlist, file recorders, sound device, tone generators, etc)
  6092. * are terminated in the conference bridge, and application can manipulate
  6093. * the interconnection between these terminations freely.
  6094. *
  6095. * The conference bridge provides powerful switching and mixing functionality
  6096. * for application. With the conference bridge, each conference slot (e.g.
  6097. * a call) can transmit to multiple destinations, and one destination can
  6098. * receive from multiple sources. If more than one media terminations are
  6099. * terminated in the same slot, the conference bridge will mix the signal
  6100. * automatically.
  6101. *
  6102. * Application connects one media termination/slot to another by calling
  6103. * #pjsua_conf_connect() function. This will establish <b>unidirectional</b>
  6104. * media flow from the source termination to the sink termination. To
  6105. * establish bidirectional media flow, application would need to make another
  6106. * call to #pjsua_conf_connect(), this time inverting the source and
  6107. * destination slots in the parameter.
  6108. *
  6109. * For example, to stream a WAV file to remote call, application may use
  6110. * the following steps:
  6111. *
  6112. \code
  6113. pj_status_t stream_to_call( pjsua_call_id call_id )
  6114. {
  6115. pjsua_player_id player_id;
  6116. status = pjsua_player_create("mysong.wav", 0, &player_id);
  6117. if (status != PJ_SUCCESS)
  6118. return status;
  6119. status = pjsua_conf_connect( pjsua_player_get_conf_port(),
  6120. pjsua_call_get_conf_port() );
  6121. }
  6122. \endcode
  6123. *
  6124. *
  6125. * Other features of PJSUA media:
  6126. * - efficient N to M interconnections between media terminations.
  6127. * - media termination can be connected to itself to create loopback
  6128. * media.
  6129. * - the media termination may have different clock rates, and resampling
  6130. * will be done automatically by conference bridge.
  6131. * - media terminations may also have different frame time; the
  6132. * conference bridge will perform the necessary bufferring to adjust
  6133. * the difference between terminations.
  6134. * - interconnections are removed automatically when media termination
  6135. * is removed from the bridge.
  6136. * - sound device may be changed even when there are active media
  6137. * interconnections.
  6138. * - correctly report call's media quality (in #pjsua_call_dump()) from
  6139. * RTCP packet exchange.
  6140. */
  6141. /**
  6142. * Use PJMEDIA for media? Set this to zero when using third party media
  6143. * stack.
  6144. */
  6145. #ifndef PJSUA_MEDIA_HAS_PJMEDIA
  6146. # define PJSUA_MEDIA_HAS_PJMEDIA 1
  6147. #endif /* PJSUA_MEDIA_HAS_PJMEDIA */
  6148. /**
  6149. * Specify whether the third party stream has the capability of retrieving
  6150. * the stream info, i.e: pjmedia_stream_get_info() and
  6151. * pjmedia_vid_stream_get_info(). Currently this capability is required
  6152. * by smart media update and call dump.
  6153. */
  6154. #ifndef PJSUA_THIRD_PARTY_STREAM_HAS_GET_INFO
  6155. # define PJSUA_THIRD_PARTY_STREAM_HAS_GET_INFO 0
  6156. #endif
  6157. /**
  6158. * Specify whether the third party stream has the capability of retrieving
  6159. * the stream statistics, i.e: pjmedia_stream_get_stat() and
  6160. * pjmedia_vid_stream_get_stat(). Currently this capability is required
  6161. * by call dump.
  6162. */
  6163. #ifndef PJSUA_THIRD_PARTY_STREAM_HAS_GET_STAT
  6164. # define PJSUA_THIRD_PARTY_STREAM_HAS_GET_STAT 0
  6165. #endif
  6166. /**
  6167. * Max ports in the conference bridge. This setting is the default value
  6168. * for pjsua_media_config.max_media_ports.
  6169. */
  6170. #ifndef PJSUA_MAX_CONF_PORTS
  6171. # define PJSUA_MAX_CONF_PORTS 254
  6172. #endif
  6173. /**
  6174. * The default clock rate to be used by the conference bridge. This setting
  6175. * is the default value for pjsua_media_config.clock_rate.
  6176. */
  6177. #ifndef PJSUA_DEFAULT_CLOCK_RATE
  6178. # define PJSUA_DEFAULT_CLOCK_RATE 16000
  6179. #endif
  6180. /**
  6181. * Default frame length in the conference bridge. This setting
  6182. * is the default value for pjsua_media_config.audio_frame_ptime.
  6183. */
  6184. #ifndef PJSUA_DEFAULT_AUDIO_FRAME_PTIME
  6185. # define PJSUA_DEFAULT_AUDIO_FRAME_PTIME 20
  6186. #endif
  6187. /**
  6188. * Default codec quality settings. This setting is the default value
  6189. * for pjsua_media_config.quality.
  6190. */
  6191. #ifndef PJSUA_DEFAULT_CODEC_QUALITY
  6192. # define PJSUA_DEFAULT_CODEC_QUALITY 8
  6193. #endif
  6194. /**
  6195. * Default iLBC mode. This setting is the default value for
  6196. * pjsua_media_config.ilbc_mode.
  6197. */
  6198. #ifndef PJSUA_DEFAULT_ILBC_MODE
  6199. # define PJSUA_DEFAULT_ILBC_MODE 30
  6200. #endif
  6201. /**
  6202. * The default echo canceller tail length. This setting
  6203. * is the default value for pjsua_media_config.ec_tail_len.
  6204. */
  6205. #ifndef PJSUA_DEFAULT_EC_TAIL_LEN
  6206. # define PJSUA_DEFAULT_EC_TAIL_LEN 200
  6207. #endif
  6208. /**
  6209. * The maximum file player.
  6210. */
  6211. #ifndef PJSUA_MAX_PLAYERS
  6212. # define PJSUA_MAX_PLAYERS 32
  6213. #endif
  6214. /**
  6215. * The maximum file player.
  6216. */
  6217. #ifndef PJSUA_MAX_RECORDERS
  6218. # define PJSUA_MAX_RECORDERS 32
  6219. #endif
  6220. /**
  6221. * Enable/disable "c=" line in SDP session level. Set to zero to disable it.
  6222. */
  6223. #ifndef PJSUA_SDP_SESS_HAS_CONN
  6224. # define PJSUA_SDP_SESS_HAS_CONN 0
  6225. #endif
  6226. /**
  6227. * Specify the delay needed when restarting the transport/listener.
  6228. * e.g: 10 msec on Linux or Android, and 0 on the other platforms.
  6229. */
  6230. #ifndef PJSUA_TRANSPORT_RESTART_DELAY_TIME
  6231. # define PJSUA_TRANSPORT_RESTART_DELAY_TIME 10
  6232. #endif
  6233. /**
  6234. * This structure describes media configuration, which will be specified
  6235. * when calling #pjsua_init(). Application MUST initialize this structure
  6236. * by calling #pjsua_media_config_default().
  6237. */
  6238. struct pjsua_media_config
  6239. {
  6240. /**
  6241. * Clock rate to be applied to the conference bridge.
  6242. * If value is zero, default clock rate will be used
  6243. * (PJSUA_DEFAULT_CLOCK_RATE, which by default is 16KHz).
  6244. */
  6245. unsigned clock_rate;
  6246. /**
  6247. * Clock rate to be applied when opening the sound device.
  6248. * If value is zero, conference bridge clock rate will be used.
  6249. */
  6250. unsigned snd_clock_rate;
  6251. /**
  6252. * Channel count be applied when opening the sound device and
  6253. * conference bridge.
  6254. */
  6255. unsigned channel_count;
  6256. /**
  6257. * Specify audio frame ptime. The value here will affect the
  6258. * samples per frame of both the sound device and the conference
  6259. * bridge. Specifying lower ptime will normally reduce the
  6260. * latency.
  6261. *
  6262. * Default value: PJSUA_DEFAULT_AUDIO_FRAME_PTIME
  6263. */
  6264. unsigned audio_frame_ptime;
  6265. /**
  6266. * Specify maximum number of media ports to be created in the
  6267. * conference bridge. Since all media terminate in the bridge
  6268. * (calls, file player, file recorder, etc), the value must be
  6269. * large enough to support all of them. However, the larger
  6270. * the value, the more computations are performed.
  6271. *
  6272. * Default value: PJSUA_MAX_CONF_PORTS
  6273. */
  6274. unsigned max_media_ports;
  6275. /**
  6276. * Specify whether the media manager should manage its own
  6277. * ioqueue for the RTP/RTCP sockets. If yes, ioqueue will be created
  6278. * and at least one worker thread will be created too. If no,
  6279. * the RTP/RTCP sockets will share the same ioqueue as SIP sockets,
  6280. * and no worker thread is needed.
  6281. *
  6282. * Normally application would say yes here, unless it wants to
  6283. * run everything from a single thread.
  6284. */
  6285. pj_bool_t has_ioqueue;
  6286. /**
  6287. * Specify the number of worker threads to handle incoming RTP
  6288. * packets. A value of one is recommended for most applications.
  6289. */
  6290. unsigned thread_cnt;
  6291. /**
  6292. * Media quality, 0-10, according to this table:
  6293. * 5-10: resampling use large filter,
  6294. * 3-4: resampling use small filter,
  6295. * 1-2: resampling use linear.
  6296. * The media quality also sets speex codec quality/complexity to the
  6297. * number.
  6298. *
  6299. * Default: PJSUA_DEFAULT_CODEC_QUALITY.
  6300. */
  6301. unsigned quality;
  6302. /**
  6303. * Specify default codec ptime.
  6304. *
  6305. * Default: 0 (codec specific)
  6306. */
  6307. unsigned ptime;
  6308. /**
  6309. * Disable VAD?
  6310. *
  6311. * Default: 0 (codec specific)
  6312. */
  6313. pj_bool_t no_vad;
  6314. /**
  6315. * iLBC mode (20 or 30).
  6316. *
  6317. * Default: 30 (PJSUA_DEFAULT_ILBC_MODE)
  6318. */
  6319. unsigned ilbc_mode;
  6320. /**
  6321. * Percentage of RTP packet to drop in TX direction
  6322. * (to simulate packet lost).
  6323. *
  6324. * Default: 0
  6325. */
  6326. unsigned tx_drop_pct;
  6327. /**
  6328. * Percentage of RTP packet to drop in RX direction
  6329. * (to simulate packet lost).
  6330. *
  6331. * Default: 0
  6332. */
  6333. unsigned rx_drop_pct;
  6334. /**
  6335. * Echo canceller options (see #pjmedia_echo_create()).
  6336. * Specify PJMEDIA_ECHO_USE_SW_ECHO here if application wishes
  6337. * to use software echo canceller instead of device EC.
  6338. *
  6339. * Default: 0.
  6340. */
  6341. unsigned ec_options;
  6342. /**
  6343. * Echo canceller tail length, in miliseconds.
  6344. *
  6345. * Default: PJSUA_DEFAULT_EC_TAIL_LEN
  6346. */
  6347. unsigned ec_tail_len;
  6348. /**
  6349. * Audio capture buffer length, in milliseconds.
  6350. *
  6351. * Default: PJMEDIA_SND_DEFAULT_REC_LATENCY
  6352. */
  6353. unsigned snd_rec_latency;
  6354. /**
  6355. * Audio playback buffer length, in milliseconds.
  6356. *
  6357. * Default: PJMEDIA_SND_DEFAULT_PLAY_LATENCY
  6358. */
  6359. unsigned snd_play_latency;
  6360. /**
  6361. * Jitter buffer initial prefetch delay in msec. The value must be
  6362. * between jb_min_pre and jb_max_pre below. If the value is 0,
  6363. * prefetching will be disabled.
  6364. *
  6365. * Default: -1 (to use default stream settings, currently 0)
  6366. */
  6367. int jb_init;
  6368. /**
  6369. * Jitter buffer minimum prefetch delay in msec.
  6370. *
  6371. * Default: -1 (to use default stream settings, currently codec ptime)
  6372. */
  6373. int jb_min_pre;
  6374. /**
  6375. * Jitter buffer maximum prefetch delay in msec.
  6376. *
  6377. * Default: -1 (to use default stream settings, currently 80% of jb_max)
  6378. */
  6379. int jb_max_pre;
  6380. /**
  6381. * Set maximum delay that can be accomodated by the jitter buffer msec.
  6382. *
  6383. * Default: -1 (to use default stream settings, currently 500 msec)
  6384. */
  6385. int jb_max;
  6386. /**
  6387. * Set the algorithm the jitter buffer uses to discard frames in order to
  6388. * adjust the latency.
  6389. *
  6390. * Default: PJMEDIA_JB_DISCARD_PROGRESSIVE
  6391. */
  6392. pjmedia_jb_discard_algo jb_discard_algo;
  6393. /**
  6394. * Enable ICE
  6395. */
  6396. pj_bool_t enable_ice;
  6397. /**
  6398. * Set the maximum number of host candidates.
  6399. *
  6400. * Default: -1 (maximum not set)
  6401. */
  6402. int ice_max_host_cands;
  6403. /**
  6404. * ICE session options.
  6405. */
  6406. pj_ice_sess_options ice_opt;
  6407. /**
  6408. * Disable RTCP component.
  6409. *
  6410. * Default: no
  6411. */
  6412. pj_bool_t ice_no_rtcp;
  6413. /**
  6414. * Send re-INVITE/UPDATE every after ICE connectivity check regardless
  6415. * the default ICE transport address is changed or not. When this is set
  6416. * to PJ_FALSE, re-INVITE/UPDATE will be sent only when the default ICE
  6417. * transport address is changed.
  6418. *
  6419. * Default: yes
  6420. */
  6421. pj_bool_t ice_always_update;
  6422. /**
  6423. * Enable TURN relay candidate in ICE.
  6424. */
  6425. pj_bool_t enable_turn;
  6426. /**
  6427. * Specify TURN domain name or host name, in in "DOMAIN:PORT" or
  6428. * "HOST:PORT" format.
  6429. */
  6430. pj_str_t turn_server;
  6431. /**
  6432. * Specify the connection type to be used to the TURN server. Valid
  6433. * values are PJ_TURN_TP_UDP, PJ_TURN_TP_TCP or PJ_TURN_TP_TLS.
  6434. *
  6435. * Default: PJ_TURN_TP_UDP
  6436. */
  6437. pj_turn_tp_type turn_conn_type;
  6438. /**
  6439. * Specify the credential to authenticate with the TURN server.
  6440. */
  6441. pj_stun_auth_cred turn_auth_cred;
  6442. /**
  6443. * This specifies TLS settings for TLS transport. It’s only applicable
  6444. * when TLS is used to connect to the TURN server.
  6445. */
  6446. pj_turn_sock_tls_cfg turn_tls_setting;
  6447. /**
  6448. * Specify idle time of sound device before it is automatically closed,
  6449. * in seconds. Use value -1 to disable the auto-close feature of sound
  6450. * device
  6451. *
  6452. * Default : 1
  6453. */
  6454. int snd_auto_close_time;
  6455. /**
  6456. * Specify whether built-in/native preview should be used if available.
  6457. * In some systems, video input devices have built-in capability to show
  6458. * preview window of the device. Using this built-in preview is preferable
  6459. * as it consumes less CPU power. If built-in preview is not available,
  6460. * the library will perform software rendering of the input. If this
  6461. * field is set to PJ_FALSE, software preview will always be used.
  6462. *
  6463. * Default: PJ_TRUE
  6464. */
  6465. pj_bool_t vid_preview_enable_native;
  6466. /**
  6467. * Disable smart media update (ticket #1568). The smart media update
  6468. * will check for any changes in the media properties after a successful
  6469. * SDP negotiation and the media will only be reinitialized when any
  6470. * change is found. When it is disabled, media streams will always be
  6471. * reinitialized after a successful SDP negotiation.
  6472. *
  6473. * Note for third party media, the smart media update requires stream info
  6474. * retrieval capability, see #PJSUA_THIRD_PARTY_STREAM_HAS_GET_INFO.
  6475. *
  6476. * Default: PJ_FALSE
  6477. */
  6478. pj_bool_t no_smart_media_update;
  6479. /**
  6480. * Omit RTCP SDES and BYE in outgoing RTCP packet, this setting will be
  6481. * applied for both audio and video streams. Note that, when RTCP SDES
  6482. * and BYE are set to be omitted, RTCP SDES will still be sent once when
  6483. * the stream starts/stops and RTCP BYE will be sent once when the stream
  6484. * stops.
  6485. *
  6486. * Default: PJ_FALSE
  6487. */
  6488. pj_bool_t no_rtcp_sdes_bye;
  6489. /**
  6490. * Optional callback for audio frame preview right before queued to
  6491. * the speaker.
  6492. * Notes:
  6493. * - application MUST NOT block or perform long operation in the callback
  6494. * as the callback may be executed in sound device thread
  6495. * - when using software echo cancellation, application MUST NOT modify
  6496. * the audio data from within the callback, otherwise the echo canceller
  6497. * will not work properly.
  6498. */
  6499. void (*on_aud_prev_play_frame)(pjmedia_frame *frame);
  6500. /**
  6501. * Optional callback for audio frame preview recorded from the microphone
  6502. * before being processed by any media component such as software echo
  6503. * canceller.
  6504. * Notes:
  6505. * - application MUST NOT block or perform long operation in the callback
  6506. * as the callback may be executed in sound device thread
  6507. * - when using software echo cancellation, application MUST NOT modify
  6508. * the audio data from within the callback, otherwise the echo canceller
  6509. * will not work properly.
  6510. */
  6511. void (*on_aud_prev_rec_frame)(pjmedia_frame *frame);
  6512. };
  6513. /**
  6514. * Use this function to initialize media config.
  6515. *
  6516. * @param cfg The media config to be initialized.
  6517. */
  6518. PJ_DECL(void) pjsua_media_config_default(pjsua_media_config *cfg);
  6519. /**
  6520. * This structure describes codec information, which can be retrieved by
  6521. * calling #pjsua_enum_codecs().
  6522. */
  6523. typedef struct pjsua_codec_info
  6524. {
  6525. /**
  6526. * Codec unique identification.
  6527. */
  6528. pj_str_t codec_id;
  6529. /**
  6530. * Codec priority (integer 0-255).
  6531. */
  6532. pj_uint8_t priority;
  6533. /**
  6534. * Codec description.
  6535. */
  6536. pj_str_t desc;
  6537. /**
  6538. * Internal buffer.
  6539. */
  6540. char buf_[64];
  6541. } pjsua_codec_info;
  6542. /**
  6543. * This structure describes information about a particular media port that
  6544. * has been registered into the conference bridge. Application can query
  6545. * this info by calling #pjsua_conf_get_port_info().
  6546. */
  6547. typedef struct pjsua_conf_port_info
  6548. {
  6549. /** Conference port number. */
  6550. pjsua_conf_port_id slot_id;
  6551. /** Port name. */
  6552. pj_str_t name;
  6553. /** Format. */
  6554. pjmedia_format format;
  6555. /** Clock rate. */
  6556. unsigned clock_rate;
  6557. /** Number of channels. */
  6558. unsigned channel_count;
  6559. /** Samples per frame */
  6560. unsigned samples_per_frame;
  6561. /** Bits per sample */
  6562. unsigned bits_per_sample;
  6563. /** Tx level adjustment. */
  6564. float tx_level_adj;
  6565. /** Rx level adjustment. */
  6566. float rx_level_adj;
  6567. /** Number of listeners in the array. */
  6568. unsigned listener_cnt;
  6569. /** Array of listeners (in other words, ports where this port is
  6570. * transmitting to).
  6571. */
  6572. pjsua_conf_port_id listeners[PJSUA_MAX_CONF_PORTS];
  6573. } pjsua_conf_port_info;
  6574. /**
  6575. * This structure holds information about custom media transport to
  6576. * be registered to pjsua.
  6577. */
  6578. typedef struct pjsua_media_transport
  6579. {
  6580. /**
  6581. * Media socket information containing the address information
  6582. * of the RTP and RTCP socket.
  6583. */
  6584. pjmedia_sock_info skinfo;
  6585. /**
  6586. * The media transport instance.
  6587. */
  6588. pjmedia_transport *transport;
  6589. } pjsua_media_transport;
  6590. /**
  6591. * Sound device index constants.
  6592. */
  6593. typedef enum pjsua_snd_dev_id
  6594. {
  6595. /**
  6596. * Constant to denote default capture device.
  6597. */
  6598. PJSUA_SND_DEFAULT_CAPTURE_DEV = PJMEDIA_AUD_DEFAULT_CAPTURE_DEV,
  6599. /**
  6600. * Constant to denote default playback device.
  6601. */
  6602. PJSUA_SND_DEFAULT_PLAYBACK_DEV = PJMEDIA_AUD_DEFAULT_PLAYBACK_DEV,
  6603. /**
  6604. * Constant to denote that no sound device is being used.
  6605. */
  6606. PJSUA_SND_NO_DEV = PJMEDIA_AUD_INVALID_DEV,
  6607. /**
  6608. * Constant to denote null sound device.
  6609. */
  6610. PJSUA_SND_NULL_DEV = -99
  6611. } pjsua_snd_dev_id;
  6612. /**
  6613. * This enumeration specifies the sound device mode.
  6614. */
  6615. typedef enum pjsua_snd_dev_mode
  6616. {
  6617. /**
  6618. * Open sound device without mic (speaker only).
  6619. */
  6620. PJSUA_SND_DEV_SPEAKER_ONLY = 1,
  6621. /**
  6622. * Do not open sound device, after setting the sound device.
  6623. */
  6624. PJSUA_SND_DEV_NO_IMMEDIATE_OPEN = 2
  6625. } pjsua_snd_dev_mode;
  6626. /**
  6627. * This structure specifies the parameters to set the sound device.
  6628. * Use pjsua_snd_dev_param_default() to initialize this structure with
  6629. * default values.
  6630. */
  6631. typedef struct pjsua_snd_dev_param
  6632. {
  6633. /**
  6634. * Capture dev id.
  6635. *
  6636. * Default: PJMEDIA_AUD_DEFAULT_CAPTURE_DEV
  6637. */
  6638. int capture_dev;
  6639. /**
  6640. * Playback dev id.
  6641. *
  6642. * Default: PJMEDIA_AUD_DEFAULT_PLAYBACK_DEV
  6643. */
  6644. int playback_dev;
  6645. /**
  6646. * Sound device mode, refer to #pjsua_snd_dev_mode.
  6647. *
  6648. * Default: 0
  6649. */
  6650. unsigned mode;
  6651. /**
  6652. * The library will maintain the global sound device settings set when
  6653. * opening the sound device for the first time and later can be modified
  6654. * using #pjsua_snd_set_setting(). These setings are then applied to any
  6655. * sound device when opening. This might be undesirable,
  6656. * e.g: output volume changes when switching sound device due to the
  6657. * use of previously set volume settings.
  6658. *
  6659. * To avoid such case, application can set this to PJ_TRUE and let the
  6660. * sound device use default settings when opening. This will also reset
  6661. * the global sound device settings.
  6662. *
  6663. * Default: PJ_FALSE
  6664. */
  6665. pj_bool_t use_default_settings;
  6666. } pjsua_snd_dev_param;
  6667. /**
  6668. * Initialize pjsua_snd_dev_param with default values.
  6669. *
  6670. * @param prm The parameter.
  6671. */
  6672. PJ_DECL(void) pjsua_snd_dev_param_default(pjsua_snd_dev_param *prm);
  6673. /**
  6674. * This structure specifies the parameters for conference ports connection.
  6675. * Use pjsua_conf_connect_param_default() to initialize this structure with
  6676. * default values.
  6677. */
  6678. typedef struct pjsua_conf_connect_param
  6679. {
  6680. /**
  6681. * Signal level adjustment from the source to the sink to make it
  6682. * louder or quieter. Value 1.0 means no level adjustment,
  6683. * while value 0 means to mute the port.
  6684. *
  6685. * Default: 1.0
  6686. */
  6687. float level;
  6688. } pjsua_conf_connect_param;
  6689. /**
  6690. * Initialize pjsua_conf_connect_param with default values.
  6691. *
  6692. * @param prm The parameter.
  6693. */
  6694. PJ_DECL(void) pjsua_conf_connect_param_default(pjsua_conf_connect_param *prm);
  6695. /**
  6696. * Get maxinum number of conference ports.
  6697. *
  6698. * @return Maximum number of ports in the conference bridge.
  6699. */
  6700. PJ_DECL(unsigned) pjsua_conf_get_max_ports(void);
  6701. /**
  6702. * Get current number of active ports in the bridge.
  6703. *
  6704. * @return The number.
  6705. */
  6706. PJ_DECL(unsigned) pjsua_conf_get_active_ports(void);
  6707. /**
  6708. * Enumerate all conference ports.
  6709. *
  6710. * @param id Array of conference port ID to be initialized.
  6711. * @param count On input, specifies max elements in the array.
  6712. * On return, it contains actual number of elements
  6713. * that have been initialized.
  6714. *
  6715. * @return PJ_SUCCESS on success, or the appropriate error code.
  6716. */
  6717. PJ_DECL(pj_status_t) pjsua_enum_conf_ports(pjsua_conf_port_id id[],
  6718. unsigned *count);
  6719. /**
  6720. * Get information about the specified conference port
  6721. *
  6722. * @param port_id Port identification.
  6723. * @param info Pointer to store the port info.
  6724. *
  6725. * @return PJ_SUCCESS on success, or the appropriate error code.
  6726. */
  6727. PJ_DECL(pj_status_t) pjsua_conf_get_port_info( pjsua_conf_port_id port_id,
  6728. pjsua_conf_port_info *info);
  6729. /**
  6730. * Add arbitrary media port to PJSUA's conference bridge. Application
  6731. * can use this function to add the media port that it creates. For
  6732. * media ports that are created by PJSUA-LIB (such as calls, file player,
  6733. * or file recorder), PJSUA-LIB will automatically add the port to
  6734. * the bridge.
  6735. *
  6736. * @param pool Pool to use.
  6737. * @param port Media port to be added to the bridge.
  6738. * @param p_id Optional pointer to receive the conference
  6739. * slot id.
  6740. *
  6741. * @return PJ_SUCCESS on success, or the appropriate error code.
  6742. */
  6743. PJ_DECL(pj_status_t) pjsua_conf_add_port(pj_pool_t *pool,
  6744. pjmedia_port *port,
  6745. pjsua_conf_port_id *p_id);
  6746. /**
  6747. * Remove arbitrary slot from the conference bridge. Application should only
  6748. * call this function if it registered the port manually with previous call
  6749. * to #pjsua_conf_add_port().
  6750. *
  6751. * @param port_id The slot id of the port to be removed.
  6752. *
  6753. * @return PJ_SUCCESS on success, or the appropriate error code.
  6754. */
  6755. PJ_DECL(pj_status_t) pjsua_conf_remove_port(pjsua_conf_port_id port_id);
  6756. /**
  6757. * Establish unidirectional media flow from souce to sink. One source
  6758. * may transmit to multiple destinations/sink. And if multiple
  6759. * sources are transmitting to the same sink, the media will be mixed
  6760. * together. Source and sink may refer to the same ID, effectively
  6761. * looping the media.
  6762. *
  6763. * If bidirectional media flow is desired, application needs to call
  6764. * this function twice, with the second one having the arguments
  6765. * reversed.
  6766. *
  6767. * @param source Port ID of the source media/transmitter.
  6768. * @param sink Port ID of the destination media/received.
  6769. *
  6770. * @return PJ_SUCCESS on success, or the appropriate error code.
  6771. */
  6772. PJ_DECL(pj_status_t) pjsua_conf_connect(pjsua_conf_port_id source,
  6773. pjsua_conf_port_id sink);
  6774. /**
  6775. * Establish unidirectional media flow from source to sink. One source
  6776. * may transmit to multiple destinations/sink. And if multiple
  6777. * sources are transmitting to the same sink, the media will be mixed
  6778. * together. Source and sink may refer to the same ID, effectively
  6779. * looping the media.
  6780. *
  6781. * Signal level from the source to the sink can be adjusted by making
  6782. * it louder or quieter via the parameter param. The level adjustment
  6783. * will apply to a specific connection only (i.e. only for the signal
  6784. * from the source to the sink), as compared to
  6785. * pjsua_conf_adjust_tx_level()/pjsua_conf_adjust_rx_level() which
  6786. * applies to all signals from/to that port. The signal adjustment
  6787. * will be cumulative, in this following order:
  6788. * signal from the source will be adjusted with the level specified
  6789. * in pjsua_conf_adjust_rx_level(), then with the level specified
  6790. * via this API, and finally with the level specified to the sink's
  6791. * pjsua_conf_adjust_tx_level().
  6792. *
  6793. * If bidirectional media flow is desired, application needs to call
  6794. * this function twice, with the second one having the arguments
  6795. * reversed.
  6796. *
  6797. * @param source Port ID of the source media/transmitter.
  6798. * @param sink Port ID of the destination media/received.
  6799. * @param prm Conference port connection param. If set to
  6800. * NULL, default values will be used.
  6801. *
  6802. * @return PJ_SUCCESS on success, or the appropriate error code.
  6803. */
  6804. PJ_DECL(pj_status_t) pjsua_conf_connect2(pjsua_conf_port_id source,
  6805. pjsua_conf_port_id sink,
  6806. const pjsua_conf_connect_param *prm);
  6807. /**
  6808. * Disconnect media flow from the source to destination port.
  6809. *
  6810. * @param source Port ID of the source media/transmitter.
  6811. * @param sink Port ID of the destination media/received.
  6812. *
  6813. * @return PJ_SUCCESS on success, or the appropriate error code.
  6814. */
  6815. PJ_DECL(pj_status_t) pjsua_conf_disconnect(pjsua_conf_port_id source,
  6816. pjsua_conf_port_id sink);
  6817. /**
  6818. * Adjust the signal level to be transmitted from the bridge to the
  6819. * specified port by making it louder or quieter.
  6820. *
  6821. * @param slot The conference bridge slot number.
  6822. * @param level Signal level adjustment. Value 1.0 means no level
  6823. * adjustment, while value 0 means to mute the port.
  6824. *
  6825. * @return PJ_SUCCESS on success, or the appropriate error code.
  6826. */
  6827. PJ_DECL(pj_status_t) pjsua_conf_adjust_tx_level(pjsua_conf_port_id slot,
  6828. float level);
  6829. /**
  6830. * Adjust the signal level to be received from the specified port (to
  6831. * the bridge) by making it louder or quieter.
  6832. *
  6833. * @param slot The conference bridge slot number.
  6834. * @param level Signal level adjustment. Value 1.0 means no level
  6835. * adjustment, while value 0 means to mute the port.
  6836. *
  6837. * @return PJ_SUCCESS on success, or the appropriate error code.
  6838. */
  6839. PJ_DECL(pj_status_t) pjsua_conf_adjust_rx_level(pjsua_conf_port_id slot,
  6840. float level);
  6841. /**
  6842. * Get last signal level transmitted to or received from the specified port.
  6843. * The signal level is an integer value in zero to 255, with zero indicates
  6844. * no signal, and 255 indicates the loudest signal level.
  6845. *
  6846. * @param slot The conference bridge slot number.
  6847. * @param tx_level Optional argument to receive the level of signal
  6848. * transmitted to the specified port (i.e. the direction
  6849. * is from the bridge to the port).
  6850. * @param rx_level Optional argument to receive the level of signal
  6851. * received from the port (i.e. the direction is from the
  6852. * port to the bridge).
  6853. *
  6854. * @return PJ_SUCCESS on success.
  6855. */
  6856. PJ_DECL(pj_status_t) pjsua_conf_get_signal_level(pjsua_conf_port_id slot,
  6857. unsigned *tx_level,
  6858. unsigned *rx_level);
  6859. /*****************************************************************************
  6860. * File player and playlist.
  6861. */
  6862. /**
  6863. * Create a file player, and automatically add this player to
  6864. * the conference bridge.
  6865. *
  6866. * @param filename The filename to be played. Currently only
  6867. * WAV files are supported, and the WAV file MUST be
  6868. * formatted as 16bit PCM mono/single channel (any
  6869. * clock rate is supported).
  6870. * Filename's length must be smaller than PJ_MAXPATH.
  6871. * @param options Optional option flag. Application may specify
  6872. * PJMEDIA_FILE_NO_LOOP to prevent playback loop.
  6873. * @param p_id Pointer to receive player ID.
  6874. *
  6875. * @return PJ_SUCCESS on success, or the appropriate error code.
  6876. */
  6877. PJ_DECL(pj_status_t) pjsua_player_create(const pj_str_t *filename,
  6878. unsigned options,
  6879. pjsua_player_id *p_id);
  6880. /**
  6881. * Create a file playlist media port, and automatically add the port
  6882. * to the conference bridge.
  6883. *
  6884. * @param file_names Array of file names to be added to the play list.
  6885. * Note that the files must have the same clock rate,
  6886. * number of channels, and number of bits per sample.
  6887. * Each filename's length must be smaller than
  6888. * PJ_MAXPATH.
  6889. * @param file_count Number of files in the array.
  6890. * @param label Optional label to be set for the media port.
  6891. * @param options Optional option flag. Application may specify
  6892. * PJMEDIA_FILE_NO_LOOP to prevent looping.
  6893. * @param p_id Optional pointer to receive player ID.
  6894. *
  6895. * @return PJ_SUCCESS on success, or the appropriate error code.
  6896. */
  6897. PJ_DECL(pj_status_t) pjsua_playlist_create(const pj_str_t file_names[],
  6898. unsigned file_count,
  6899. const pj_str_t *label,
  6900. unsigned options,
  6901. pjsua_player_id *p_id);
  6902. /**
  6903. * Get conference port ID associated with player or playlist.
  6904. *
  6905. * @param id The file player ID.
  6906. *
  6907. * @return Conference port ID associated with this player.
  6908. */
  6909. PJ_DECL(pjsua_conf_port_id) pjsua_player_get_conf_port(pjsua_player_id id);
  6910. /**
  6911. * Get the media port for the player or playlist.
  6912. *
  6913. * @param id The player ID.
  6914. * @param p_port The media port associated with the player.
  6915. *
  6916. * @return PJ_SUCCESS on success.
  6917. */
  6918. PJ_DECL(pj_status_t) pjsua_player_get_port(pjsua_player_id id,
  6919. pjmedia_port **p_port);
  6920. /**
  6921. * Get additional info about the file player. This operation is not valid
  6922. * for playlist.
  6923. *
  6924. * @param id The file player ID.
  6925. * @param info The info.
  6926. *
  6927. * @return PJ_SUCCESS on success or the appropriate error code.
  6928. */
  6929. PJ_DECL(pj_status_t) pjsua_player_get_info(pjsua_player_id id,
  6930. pjmedia_wav_player_info *info);
  6931. /**
  6932. * Get playback position. This operation is not valid for playlist.
  6933. *
  6934. * @param id The file player ID.
  6935. *
  6936. * @return The current playback position, in samples. On error,
  6937. * return the error code as negative value.
  6938. */
  6939. PJ_DECL(pj_ssize_t) pjsua_player_get_pos(pjsua_player_id id);
  6940. /**
  6941. * Set playback position. This operation is not valid for playlist.
  6942. *
  6943. * @param id The file player ID.
  6944. * @param samples The playback position, in samples. Application can
  6945. * specify zero to re-start the playback.
  6946. *
  6947. * @return PJ_SUCCESS on success, or the appropriate error code.
  6948. */
  6949. PJ_DECL(pj_status_t) pjsua_player_set_pos(pjsua_player_id id,
  6950. pj_uint32_t samples);
  6951. /**
  6952. * Close the file of playlist, remove the player from the bridge, and free
  6953. * resources associated with the file player or playlist.
  6954. *
  6955. * @param id The file player ID.
  6956. *
  6957. * @return PJ_SUCCESS on success, or the appropriate error code.
  6958. */
  6959. PJ_DECL(pj_status_t) pjsua_player_destroy(pjsua_player_id id);
  6960. /*****************************************************************************
  6961. * File recorder.
  6962. */
  6963. /**
  6964. * Create a file recorder, and automatically connect this recorder to
  6965. * the conference bridge. The recorder currently supports recording WAV file.
  6966. * The type of the recorder to use is determined by the extension of the file
  6967. * (e.g. ".wav").
  6968. *
  6969. * @param filename Output file name. The function will determine the
  6970. * default format to be used based on the file extension.
  6971. * Currently ".wav" is supported on all platforms.
  6972. * Filename's length must be smaller than PJ_MAXPATH.
  6973. * @param enc_type Optionally specify the type of encoder to be used to
  6974. * compress the media, if the file can support different
  6975. * encodings. This value must be zero for now.
  6976. * @param enc_param Optionally specify codec specific parameter to be
  6977. * passed to the file writer.
  6978. * For .WAV recorder, this value must be NULL.
  6979. * @param max_size Maximum file size. Specify zero or -1 to remove size
  6980. * limitation. This value must be zero or -1 for now.
  6981. * @param options Optional options.
  6982. * @param p_id Pointer to receive the recorder instance.
  6983. *
  6984. * @return PJ_SUCCESS on success, or the appropriate error code.
  6985. */
  6986. PJ_DECL(pj_status_t) pjsua_recorder_create(const pj_str_t *filename,
  6987. unsigned enc_type,
  6988. void *enc_param,
  6989. pj_ssize_t max_size,
  6990. unsigned options,
  6991. pjsua_recorder_id *p_id);
  6992. /**
  6993. * Get conference port associated with recorder.
  6994. *
  6995. * @param id The recorder ID.
  6996. *
  6997. * @return Conference port ID associated with this recorder.
  6998. */
  6999. PJ_DECL(pjsua_conf_port_id) pjsua_recorder_get_conf_port(pjsua_recorder_id id);
  7000. /**
  7001. * Get the media port for the recorder.
  7002. *
  7003. * @param id The recorder ID.
  7004. * @param p_port The media port associated with the recorder.
  7005. *
  7006. * @return PJ_SUCCESS on success.
  7007. */
  7008. PJ_DECL(pj_status_t) pjsua_recorder_get_port(pjsua_recorder_id id,
  7009. pjmedia_port **p_port);
  7010. /**
  7011. * Destroy recorder (this will complete recording).
  7012. *
  7013. * @param id The recorder ID.
  7014. *
  7015. * @return PJ_SUCCESS on success, or the appropriate error code.
  7016. */
  7017. PJ_DECL(pj_status_t) pjsua_recorder_destroy(pjsua_recorder_id id);
  7018. /*****************************************************************************
  7019. * Sound devices.
  7020. */
  7021. /**
  7022. * Enum all audio devices installed in the system.
  7023. *
  7024. * @param info Array of info to be initialized.
  7025. * @param count On input, specifies max elements in the array.
  7026. * On return, it contains actual number of elements
  7027. * that have been initialized.
  7028. *
  7029. * @return PJ_SUCCESS on success, or the appropriate error code.
  7030. */
  7031. PJ_DECL(pj_status_t) pjsua_enum_aud_devs(pjmedia_aud_dev_info info[],
  7032. unsigned *count);
  7033. /**
  7034. * Enum all sound devices installed in the system (old API).
  7035. *
  7036. * @param info Array of info to be initialized.
  7037. * @param count On input, specifies max elements in the array.
  7038. * On return, it contains actual number of elements
  7039. * that have been initialized.
  7040. *
  7041. * @return PJ_SUCCESS on success, or the appropriate error code.
  7042. */
  7043. PJ_DECL(pj_status_t) pjsua_enum_snd_devs(pjmedia_snd_dev_info info[],
  7044. unsigned *count);
  7045. /**
  7046. * Get currently active sound devices. If sound devices has not been created
  7047. * (for example when pjsua_start() is not called), it is possible that
  7048. * the function returns PJ_SUCCESS with -1 as device IDs.
  7049. * See also #pjsua_snd_dev_id constants.
  7050. *
  7051. * @param capture_dev On return it will be filled with device ID of the
  7052. * capture device.
  7053. * @param playback_dev On return it will be filled with device ID of the
  7054. * device ID of the playback device.
  7055. *
  7056. * @return PJ_SUCCESS on success, or the appropriate error code.
  7057. */
  7058. PJ_DECL(pj_status_t) pjsua_get_snd_dev(int *capture_dev,
  7059. int *playback_dev);
  7060. /**
  7061. * Select or change sound device. Application may call this function at
  7062. * any time to replace current sound device.
  7063. *
  7064. * Note that this function will always try to open the sound device
  7065. * immediately. If immediate open is not preferred, use pjsua_set_snd_dev2()
  7066. * with PJSUA_SND_DEV_NO_IMMEDIATE_OPEN flag.
  7067. *
  7068. * @param capture_dev Device ID of the capture device.
  7069. * @param playback_dev Device ID of the playback device.
  7070. *
  7071. * @return PJ_SUCCESS on success, or the appropriate error code.
  7072. */
  7073. PJ_DECL(pj_status_t) pjsua_set_snd_dev(int capture_dev,
  7074. int playback_dev);
  7075. /**
  7076. * Get sound device parameters such as playback & capture device IDs and mode.
  7077. *
  7078. * @param snd_param On return, it is set with sound device param.
  7079. *
  7080. * @return PJ_SUCCESS on success, or the appropriate error code.
  7081. */
  7082. PJ_DECL(pj_status_t) pjsua_get_snd_dev2(pjsua_snd_dev_param *snd_param);
  7083. /**
  7084. * Select or change sound device according to the specified param.
  7085. *
  7086. * @param snd_param Sound device param.
  7087. *
  7088. * @return PJ_SUCCESS on success, or the appropriate error code.
  7089. */
  7090. PJ_DECL(pj_status_t) pjsua_set_snd_dev2(const pjsua_snd_dev_param *snd_param);
  7091. /**
  7092. * Set pjsua to use null sound device. The null sound device only provides
  7093. * the timing needed by the conference bridge, and will not interract with
  7094. * any hardware.
  7095. *
  7096. * @return PJ_SUCCESS on success, or the appropriate error code.
  7097. */
  7098. PJ_DECL(pj_status_t) pjsua_set_null_snd_dev(void);
  7099. /**
  7100. * Disconnect the main conference bridge from any sound devices, and let
  7101. * application connect the bridge to it's own sound device/master port.
  7102. *
  7103. * @return The port interface of the conference bridge,
  7104. * so that application can connect this to it's own
  7105. * sound device or master port.
  7106. */
  7107. PJ_DECL(pjmedia_port*) pjsua_set_no_snd_dev(void);
  7108. /**
  7109. * Change the echo cancellation settings.
  7110. *
  7111. * The behavior of this function depends on whether the sound device is
  7112. * currently active, and if it is, whether device or software AEC is
  7113. * being used.
  7114. *
  7115. * If the sound device is currently active, and if the device supports AEC,
  7116. * this function will forward the change request to the device and it will
  7117. * be up to the device on whether support the request. If software AEC is
  7118. * being used (the software EC will be used if the device does not support
  7119. * AEC), this function will change the software EC settings. In all cases,
  7120. * the setting will be saved for future opening of the sound device.
  7121. *
  7122. * If the sound device is not currently active, this will only change the
  7123. * default AEC settings and the setting will be applied next time the
  7124. * sound device is opened.
  7125. *
  7126. * @param tail_ms The tail length, in miliseconds. Set to zero to
  7127. * disable AEC.
  7128. * @param options Options to be passed to pjmedia_echo_create().
  7129. * Normally the value should be zero.
  7130. *
  7131. * @return PJ_SUCCESS on success.
  7132. */
  7133. PJ_DECL(pj_status_t) pjsua_set_ec(unsigned tail_ms, unsigned options);
  7134. /**
  7135. * Get current echo canceller tail length.
  7136. *
  7137. * @param p_tail_ms Pointer to receive the tail length, in miliseconds.
  7138. * If AEC is disabled, the value will be zero.
  7139. *
  7140. * @return PJ_SUCCESS on success.
  7141. */
  7142. PJ_DECL(pj_status_t) pjsua_get_ec_tail(unsigned *p_tail_ms);
  7143. /**
  7144. * Get echo canceller statistics.
  7145. *
  7146. * @param p_stat Pointer to receive the stat.
  7147. *
  7148. * @return PJ_SUCCESS on success, or the appropriate error
  7149. * code.
  7150. */
  7151. PJ_DECL(pj_status_t) pjsua_get_ec_stat(pjmedia_echo_stat *p_stat);
  7152. /**
  7153. * Check whether the sound device is currently active. The sound device
  7154. * may be inactive if the application has set the auto close feature to
  7155. * non-zero (the snd_auto_close_time setting in #pjsua_media_config), or
  7156. * if null sound device or no sound device has been configured via the
  7157. * #pjsua_set_no_snd_dev() function.
  7158. */
  7159. PJ_DECL(pj_bool_t) pjsua_snd_is_active(void);
  7160. /**
  7161. * Configure sound device setting to the sound device being used. If sound
  7162. * device is currently active, the function will forward the setting to the
  7163. * sound device instance to be applied immediately, if it supports it.
  7164. *
  7165. * The setting will be saved for future opening of the sound device, if the
  7166. * "keep" argument is set to non-zero. If the sound device is currently
  7167. * inactive, and the "keep" argument is false, this function will return
  7168. * error.
  7169. *
  7170. * Note that in case the setting is kept for future use, it will be applied
  7171. * to any devices, even when application has changed the sound device to be
  7172. * used. To reset the setting, application can call #pjsua_set_snd_dev2()
  7173. * with \a use_default_settings set to PJ_TRUE.
  7174. *
  7175. * Note also that the echo cancellation setting should be set with
  7176. * #pjsua_set_ec() API instead.
  7177. *
  7178. * See also #pjmedia_aud_stream_set_cap() for more information about setting
  7179. * an audio device capability.
  7180. *
  7181. * @param cap The sound device setting to change.
  7182. * @param pval Pointer to value. Please see #pjmedia_aud_dev_cap
  7183. * documentation about the type of value to be
  7184. * supplied for each setting.
  7185. * @param keep Specify whether the setting is to be kept for future
  7186. * use.
  7187. *
  7188. * @return PJ_SUCCESS on success or the appropriate error code.
  7189. */
  7190. PJ_DECL(pj_status_t) pjsua_snd_set_setting(pjmedia_aud_dev_cap cap,
  7191. const void *pval,
  7192. pj_bool_t keep);
  7193. /**
  7194. * Retrieve a sound device setting. If sound device is currently active,
  7195. * the function will forward the request to the sound device. If sound device
  7196. * is currently inactive, and if application had previously set the setting
  7197. * and mark the setting as kept, then that setting will be returned.
  7198. * Otherwise, this function will return error.
  7199. *
  7200. * Note that echo cancellation settings should be retrieved with
  7201. * #pjsua_get_ec_tail() API instead.
  7202. *
  7203. * @param cap The sound device setting to retrieve.
  7204. * @param pval Pointer to receive the value.
  7205. * Please see #pjmedia_aud_dev_cap documentation about
  7206. * the type of value to be supplied for each setting.
  7207. *
  7208. * @return PJ_SUCCESS on success or the appropriate error code.
  7209. */
  7210. PJ_DECL(pj_status_t) pjsua_snd_get_setting(pjmedia_aud_dev_cap cap,
  7211. void *pval);
  7212. /**
  7213. * Opaque type of extra sound device, an additional sound device
  7214. * beside the primary sound device (the one instantiated via
  7215. * pjsua_set_snd_dev() or pjsua_set_snd_dev2()). This sound device is
  7216. * also registered to conference bridge so it can be used as a normal
  7217. * conference bridge port, e.g: connect it to/from other ports,
  7218. * adjust/check audio level, etc. The conference bridge port ID can be
  7219. * queried using pjsua_ext_snd_dev_get_conf_port().
  7220. *
  7221. * Application may also use this API to improve media clock. Normally
  7222. * media clock is driven by sound device in master port, but unfortunately
  7223. * some sound devices may produce jittery clock. To improve media clock,
  7224. * application can install Null Sound Device (i.e: using
  7225. * pjsua_set_null_snd_dev()), which will act as a master port, and instantiate
  7226. * the sound device as extra sound device.
  7227. *
  7228. * Note that extra sound device will not have auto-close upon idle feature.
  7229. * Also note that currently extra sound device only supports mono channel.
  7230. */
  7231. typedef struct pjsua_ext_snd_dev pjsua_ext_snd_dev;
  7232. /**
  7233. * Create an extra sound device and register it to conference bridge.
  7234. *
  7235. * @param param Sound device port param. Currently this only supports
  7236. * mono channel, so channel count must be set to 1.
  7237. * @param p_snd The extra sound device instance.
  7238. *
  7239. * @return PJ_SUCCESS on success or the appropriate error code.
  7240. */
  7241. PJ_DECL(pj_status_t) pjsua_ext_snd_dev_create(pjmedia_snd_port_param *param,
  7242. pjsua_ext_snd_dev **p_snd);
  7243. /**
  7244. * Destroy an extra sound device and unregister it from conference bridge.
  7245. *
  7246. * @param snd The extra sound device instance.
  7247. *
  7248. * @return PJ_SUCCESS on success or the appropriate error code.
  7249. */
  7250. PJ_DECL(pj_status_t) pjsua_ext_snd_dev_destroy(pjsua_ext_snd_dev *snd);
  7251. /**
  7252. * Get sound port instance of an extra sound device.
  7253. *
  7254. * @param snd The extra sound device instance.
  7255. *
  7256. * @return The sound port instance.
  7257. */
  7258. PJ_DECL(pjmedia_snd_port*) pjsua_ext_snd_dev_get_snd_port(
  7259. pjsua_ext_snd_dev *snd);
  7260. /**
  7261. * Get conference port ID of an extra sound device.
  7262. *
  7263. * @param snd The extra sound device instance.
  7264. *
  7265. * @return The conference port ID.
  7266. */
  7267. PJ_DECL(pjsua_conf_port_id) pjsua_ext_snd_dev_get_conf_port(
  7268. pjsua_ext_snd_dev *snd);
  7269. /*****************************************************************************
  7270. * Codecs.
  7271. */
  7272. /**
  7273. * Enum all supported codecs in the system.
  7274. *
  7275. * @param id Array of ID to be initialized.
  7276. * @param count On input, specifies max elements in the array.
  7277. * On return, it contains actual number of elements
  7278. * that have been initialized.
  7279. *
  7280. * @return PJ_SUCCESS on success, or the appropriate error code.
  7281. */
  7282. PJ_DECL(pj_status_t) pjsua_enum_codecs( pjsua_codec_info id[],
  7283. unsigned *count );
  7284. /**
  7285. * Change codec priority.
  7286. *
  7287. * @param codec_id Codec ID, which is a string that uniquely identify
  7288. * the codec (such as "speex/8000"). Please see pjsua
  7289. * manual or pjmedia codec reference for details.
  7290. * @param priority Codec priority, 0-255, where zero means to disable
  7291. * the codec.
  7292. *
  7293. * @return PJ_SUCCESS on success, or the appropriate error code.
  7294. */
  7295. PJ_DECL(pj_status_t) pjsua_codec_set_priority( const pj_str_t *codec_id,
  7296. pj_uint8_t priority );
  7297. /**
  7298. * Get codec parameters.
  7299. *
  7300. * @param codec_id Codec ID.
  7301. * @param param Structure to receive codec parameters.
  7302. *
  7303. * @return PJ_SUCCESS on success, or the appropriate error code.
  7304. */
  7305. PJ_DECL(pj_status_t) pjsua_codec_get_param( const pj_str_t *codec_id,
  7306. pjmedia_codec_param *param );
  7307. /**
  7308. * Set codec parameters.
  7309. *
  7310. * @param codec_id Codec ID.
  7311. * @param param Codec parameter to set. Set to NULL to reset
  7312. * codec parameter to library default settings.
  7313. *
  7314. * @return PJ_SUCCESS on success, or the appropriate error code.
  7315. */
  7316. PJ_DECL(pj_status_t) pjsua_codec_set_param( const pj_str_t *codec_id,
  7317. const pjmedia_codec_param *param);
  7318. #if DISABLED_FOR_TICKET_1185
  7319. /**
  7320. * Create UDP media transports for all the calls. This function creates
  7321. * one UDP media transport for each call.
  7322. *
  7323. * @param cfg Media transport configuration. The "port" field in the
  7324. * configuration is used as the start port to bind the
  7325. * sockets.
  7326. *
  7327. * @return PJ_SUCCESS on success, or the appropriate error code.
  7328. */
  7329. PJ_DECL(pj_status_t)
  7330. pjsua_media_transports_create(const pjsua_transport_config *cfg);
  7331. /**
  7332. * Register custom media transports to be used by calls. There must
  7333. * enough media transports for all calls.
  7334. *
  7335. * @param tp The media transport array.
  7336. * @param count Number of elements in the array. This number MUST
  7337. * match the number of maximum calls configured when
  7338. * pjsua is created.
  7339. * @param auto_delete Flag to indicate whether the transports should be
  7340. * destroyed when pjsua is shutdown.
  7341. *
  7342. * @return PJ_SUCCESS on success, or the appropriate error code.
  7343. */
  7344. PJ_DECL(pj_status_t)
  7345. pjsua_media_transports_attach( pjsua_media_transport tp[],
  7346. unsigned count,
  7347. pj_bool_t auto_delete);
  7348. #endif
  7349. /* end of MEDIA API */
  7350. /**
  7351. * @}
  7352. */
  7353. /*****************************************************************************
  7354. * VIDEO API
  7355. */
  7356. /**
  7357. * @defgroup PJSUA_LIB_VIDEO PJSUA-API Video
  7358. * @ingroup PJSUA_LIB
  7359. * @brief Video support
  7360. * @{
  7361. */
  7362. /*
  7363. * Video devices API
  7364. */
  7365. /**
  7366. * Controls whether PJSUA-LIB should not initialize video device subsystem
  7367. * in the PJSUA initialization. The video device subsystem initialization
  7368. * may need to open cameras to enumerates available cameras and their
  7369. * capabilities, which may not be preferable for some applications because
  7370. * it may trigger privacy-alert/permission notification on application startup
  7371. * (e.g: on Android app).
  7372. *
  7373. * If this is set, later application should manually initialize video device
  7374. * subsystem when it needs to use any video devices (camera and renderer),
  7375. * i.e: by invoking pjmedia_vid_dev_subsys_init() for PJSUA or
  7376. * VidDevManager::initSubsys() for PJSUA2.
  7377. *
  7378. * Note that pjmedia_vid_dev_subsys_init() should not be called multiple
  7379. * times (unless each has corresponding pjmedia_vid_dev_subsys_shutdown()),
  7380. * while VidDevManager::initSubsys() is safe to be called multiple times.
  7381. *
  7382. * Default: 0 (no)
  7383. */
  7384. #ifndef PJSUA_DONT_INIT_VID_DEV_SUBSYS
  7385. # define PJSUA_DONT_INIT_VID_DEV_SUBSYS 0
  7386. #endif
  7387. /**
  7388. * Get the number of video devices installed in the system.
  7389. *
  7390. * @return The number of devices.
  7391. */
  7392. PJ_DECL(unsigned) pjsua_vid_dev_count(void);
  7393. /**
  7394. * Retrieve the video device info for the specified device index.
  7395. *
  7396. * @param id The device index.
  7397. * @param vdi Device info to be initialized.
  7398. *
  7399. * @return PJ_SUCCESS on success, or the appropriate error code.
  7400. */
  7401. PJ_DECL(pj_status_t) pjsua_vid_dev_get_info(pjmedia_vid_dev_index id,
  7402. pjmedia_vid_dev_info *vdi);
  7403. /**
  7404. * Check whether the video capture device is currently active, i.e. if
  7405. * a video preview has been started or there is a video call using
  7406. * the device. This function will return PJ_FALSE for video renderer device.
  7407. *
  7408. * @param id The video device index.
  7409. *
  7410. * @return PJ_TRUE if active, PJ_FALSE otherwise.
  7411. */
  7412. PJ_DECL(pj_bool_t) pjsua_vid_dev_is_active(pjmedia_vid_dev_index id);
  7413. /**
  7414. * Configure the capability of a video capture device. If the device is
  7415. * currently active (i.e. if there is a video call using the device or
  7416. * a video preview has been started), the function will forward the setting
  7417. * to the video device instance to be applied immediately, if it supports it.
  7418. *
  7419. * The setting will be saved for future opening of the video device, if the
  7420. * "keep" argument is set to non-zero. If the video device is currently
  7421. * inactive, and the "keep" argument is false, this function will return
  7422. * error.
  7423. *
  7424. * Note: This function will only works for video capture devices. To
  7425. * configure the setting of video renderer device instances, use
  7426. * pjsua_vid_win API instead.
  7427. *
  7428. * Warning: If application refreshes the video device list, it needs to
  7429. * manually update the settings to reflect the newly updated video device
  7430. * indexes. See #pjmedia_vid_dev_refresh() for more information.
  7431. *
  7432. * See also pjmedia_vid_stream_set_cap() for more information about setting
  7433. * a video device capability.
  7434. *
  7435. * @param id The video device index.
  7436. * @param cap The video device capability to change.
  7437. * @param pval Pointer to value. Please see #pjmedia_vid_dev_cap
  7438. * documentation about the type of value to be
  7439. * supplied for each setting.
  7440. * @param keep (see description)
  7441. *
  7442. * @return PJ_SUCCESS on success or the appropriate error code.
  7443. */
  7444. PJ_DECL(pj_status_t) pjsua_vid_dev_set_setting(pjmedia_vid_dev_index id,
  7445. pjmedia_vid_dev_cap cap,
  7446. const void *pval,
  7447. pj_bool_t keep);
  7448. /**
  7449. * Retrieve the value of a video capture device setting. If the device is
  7450. * currently active (i.e. if there is a video call using the device or
  7451. * a video preview has been started), the function will forward the request
  7452. * to the video device. If video device is currently inactive, and if
  7453. * application had previously set the setting and mark the setting as kept,
  7454. * then that setting will be returned. Otherwise, this function will return
  7455. * error.
  7456. * The function only works for video capture device.
  7457. *
  7458. * @param id The video device index.
  7459. * @param cap The video device capability to retrieve.
  7460. * @param pval Pointer to receive the value.
  7461. * Please see #pjmedia_vid_dev_cap documentation about
  7462. * the type of value to be supplied for each setting.
  7463. *
  7464. * @return PJ_SUCCESS on success or the appropriate error code.
  7465. */
  7466. PJ_DECL(pj_status_t) pjsua_vid_dev_get_setting(pjmedia_vid_dev_index id,
  7467. pjmedia_vid_dev_cap cap,
  7468. void *pval);
  7469. /**
  7470. * Enum all video devices installed in the system.
  7471. *
  7472. * @param info Array of info to be initialized.
  7473. * @param count On input, specifies max elements in the array.
  7474. * On return, it contains actual number of elements
  7475. * that have been initialized.
  7476. *
  7477. * @return PJ_SUCCESS on success, or the appropriate error code.
  7478. */
  7479. PJ_DECL(pj_status_t) pjsua_vid_enum_devs(pjmedia_vid_dev_info info[],
  7480. unsigned *count);
  7481. /*
  7482. * Video preview API
  7483. */
  7484. /**
  7485. * Parameters for starting video preview with pjsua_vid_preview_start().
  7486. * Application should initialize this structure with
  7487. * pjsua_vid_preview_param_default().
  7488. */
  7489. typedef struct pjsua_vid_preview_param
  7490. {
  7491. /**
  7492. * Device ID for the video renderer to be used for rendering the
  7493. * capture stream for preview. This parameter is ignored if native
  7494. * preview is being used.
  7495. *
  7496. * Default: PJMEDIA_VID_DEFAULT_RENDER_DEV
  7497. */
  7498. pjmedia_vid_dev_index rend_id;
  7499. /**
  7500. * Show window initially.
  7501. *
  7502. * Default: PJ_TRUE.
  7503. */
  7504. pj_bool_t show;
  7505. /**
  7506. * Window flags. The value is a bitmask combination of
  7507. * #pjmedia_vid_dev_wnd_flag.
  7508. *
  7509. * Default: 0.
  7510. */
  7511. unsigned wnd_flags;
  7512. /**
  7513. * Media format. Initialize this with #pjmedia_format_init_video().
  7514. * If left unitialized, this parameter will not be used.
  7515. */
  7516. pjmedia_format format;
  7517. /**
  7518. * Optional output window to be used to display the video preview.
  7519. * This parameter will only be used if the video device supports
  7520. * PJMEDIA_VID_DEV_CAP_OUTPUT_WINDOW capability and the capability
  7521. * is not read-only.
  7522. */
  7523. pjmedia_vid_dev_hwnd wnd;
  7524. } pjsua_vid_preview_param;
  7525. /**
  7526. * Initialize pjsua_vid_preview_param
  7527. *
  7528. * @param p The parameter to be initialized.
  7529. */
  7530. PJ_DECL(void) pjsua_vid_preview_param_default(pjsua_vid_preview_param *p);
  7531. /**
  7532. * Determine if the specified video input device has built-in native
  7533. * preview capability. This is a convenience function that is equal to
  7534. * querying device's capability for PJMEDIA_VID_DEV_CAP_INPUT_PREVIEW
  7535. * capability.
  7536. *
  7537. * @param id The capture device ID.
  7538. *
  7539. * @return PJ_TRUE if it has.
  7540. */
  7541. PJ_DECL(pj_bool_t) pjsua_vid_preview_has_native(pjmedia_vid_dev_index id);
  7542. /**
  7543. * Start video preview window for the specified capture device.
  7544. *
  7545. * @param id The capture device ID where its preview will be
  7546. * started.
  7547. * @param p Optional video preview parameters. Specify NULL
  7548. * to use default values.
  7549. *
  7550. * @return PJ_SUCCESS on success, or the appropriate error code.
  7551. */
  7552. PJ_DECL(pj_status_t) pjsua_vid_preview_start(pjmedia_vid_dev_index id,
  7553. const pjsua_vid_preview_param *p);
  7554. /**
  7555. * Get the preview window handle associated with the capture device, if any.
  7556. *
  7557. * @param id The capture device ID.
  7558. *
  7559. * @return The window ID of the preview window for the
  7560. * specified capture device ID, or PJSUA_INVALID_ID if
  7561. * preview has not been started for the device.
  7562. */
  7563. PJ_DECL(pjsua_vid_win_id) pjsua_vid_preview_get_win(pjmedia_vid_dev_index id);
  7564. /**
  7565. * Get video conference slot ID of the specified capture device, if any.
  7566. *
  7567. * @param id The capture device ID.
  7568. *
  7569. * @return The video conference slot ID of the specified capture
  7570. * device ID, or PJSUA_INVALID_ID if preview has not been
  7571. * started for the device.
  7572. */
  7573. PJ_DECL(pjsua_conf_port_id) pjsua_vid_preview_get_vid_conf_port(
  7574. pjmedia_vid_dev_index id);
  7575. /**
  7576. * Stop video preview.
  7577. *
  7578. * @param id The capture device ID.
  7579. *
  7580. * @return PJ_SUCCESS on success, or the appropriate error code.
  7581. */
  7582. PJ_DECL(pj_status_t) pjsua_vid_preview_stop(pjmedia_vid_dev_index id);
  7583. /*
  7584. * Video window manipulation API.
  7585. */
  7586. /**
  7587. * This structure describes video window info.
  7588. */
  7589. typedef struct pjsua_vid_win_info
  7590. {
  7591. /**
  7592. * Flag to indicate whether this window is a native window,
  7593. * such as created by built-in preview device. If this field is
  7594. * PJ_TRUE, only the native window handle field of this
  7595. * structure is valid.
  7596. */
  7597. pj_bool_t is_native;
  7598. /**
  7599. * Native window handle.
  7600. */
  7601. pjmedia_vid_dev_hwnd hwnd;
  7602. /**
  7603. * Renderer device ID.
  7604. */
  7605. pjmedia_vid_dev_index rdr_dev;
  7606. /**
  7607. * Renderer port ID in the video conference bridge.
  7608. */
  7609. pjsua_conf_port_id slot_id;
  7610. /**
  7611. * Window show status. The window is hidden if false.
  7612. */
  7613. pj_bool_t show;
  7614. /**
  7615. * Window position.
  7616. */
  7617. pjmedia_coord pos;
  7618. /**
  7619. * Window size.
  7620. */
  7621. pjmedia_rect_size size;
  7622. } pjsua_vid_win_info;
  7623. /**
  7624. * Enumerates all video windows.
  7625. *
  7626. * @param wids Array of window ID to be initialized.
  7627. * @param count On input, specifies max elements in the array.
  7628. * On return, it contains actual number of elements
  7629. * that have been initialized.
  7630. *
  7631. * @return PJ_SUCCESS on success, or the appropriate error code.
  7632. */
  7633. PJ_DECL(pj_status_t) pjsua_vid_enum_wins(pjsua_vid_win_id wids[],
  7634. unsigned *count);
  7635. /**
  7636. * Get window info.
  7637. *
  7638. * @param wid The video window ID.
  7639. * @param wi The video window info to be initialized.
  7640. *
  7641. * @return PJ_SUCCESS on success, or the appropriate error code.
  7642. */
  7643. PJ_DECL(pj_status_t) pjsua_vid_win_get_info(pjsua_vid_win_id wid,
  7644. pjsua_vid_win_info *wi);
  7645. /**
  7646. * Show or hide window. This operation is not valid for native windows
  7647. * (pjsua_vid_win_info.is_native=PJ_TRUE), on which native windowing API
  7648. * must be used instead.
  7649. *
  7650. * @param wid The video window ID.
  7651. * @param show Set to PJ_TRUE to show the window, PJ_FALSE to
  7652. * hide the window.
  7653. *
  7654. * @return PJ_SUCCESS on success, or the appropriate error code.
  7655. */
  7656. PJ_DECL(pj_status_t) pjsua_vid_win_set_show(pjsua_vid_win_id wid,
  7657. pj_bool_t show);
  7658. /**
  7659. * Set video window position. This operation is not valid for native windows
  7660. * (pjsua_vid_win_info.is_native=PJ_TRUE), on which native windowing API
  7661. * must be used instead.
  7662. *
  7663. * @param wid The video window ID.
  7664. * @param pos The window position.
  7665. *
  7666. * @return PJ_SUCCESS on success, or the appropriate error code.
  7667. */
  7668. PJ_DECL(pj_status_t) pjsua_vid_win_set_pos(pjsua_vid_win_id wid,
  7669. const pjmedia_coord *pos);
  7670. /**
  7671. * Resize window. This operation is not valid for native windows
  7672. * (pjsua_vid_win_info.is_native=PJ_TRUE), on which native windowing API
  7673. * must be used instead.
  7674. *
  7675. * @param wid The video window ID.
  7676. * @param size The new window size.
  7677. *
  7678. * @return PJ_SUCCESS on success, or the appropriate error code.
  7679. */
  7680. PJ_DECL(pj_status_t) pjsua_vid_win_set_size(pjsua_vid_win_id wid,
  7681. const pjmedia_rect_size *size);
  7682. /**
  7683. * Set output window. This operation is valid only when the underlying
  7684. * video device supports PJMEDIA_VIDEO_DEV_CAP_OUTPUT_WINDOW capability AND
  7685. * allows the output window to be changed on-the-fly. Currently it is only
  7686. * supported on Android.
  7687. *
  7688. * @param wid The video window ID.
  7689. * @param win The new output window.
  7690. *
  7691. * @return PJ_SUCCESS on success, or the appropriate error code.
  7692. */
  7693. PJ_DECL(pj_status_t) pjsua_vid_win_set_win(pjsua_vid_win_id wid,
  7694. const pjmedia_vid_dev_hwnd *win);
  7695. /**
  7696. * Rotate the video window. This function will change the video orientation
  7697. * and also possibly the video window size (width and height get swapped).
  7698. * This operation is not valid for native windows (pjsua_vid_win_info.is_native
  7699. * =PJ_TRUE), on which native windowing API must be used instead.
  7700. *
  7701. * @param wid The video window ID.
  7702. * @param angle The rotation angle in degrees, must be multiple of 90.
  7703. * Specify positive value for clockwise rotation or
  7704. * negative value for counter-clockwise rotation.
  7705. *
  7706. * @return PJ_SUCCESS on success, or the appropriate error code.
  7707. */
  7708. PJ_DECL(pj_status_t) pjsua_vid_win_rotate(pjsua_vid_win_id wid,
  7709. int angle);
  7710. /**
  7711. * Set video window full-screen. This operation is valid only when the
  7712. * underlying video device supports PJMEDIA_VID_DEV_CAP_OUTPUT_FULLSCREEN
  7713. * capability. Currently it is only supported on SDL backend.
  7714. *
  7715. * @param wid The video window ID.
  7716. * @param mode Fullscreen mode, see pjmedia_vid_dev_fullscreen_flag.
  7717. *
  7718. * @return PJ_SUCCESS on success, or the appropriate error code.
  7719. */
  7720. PJ_DECL(pj_status_t) pjsua_vid_win_set_fullscreen(
  7721. pjsua_vid_win_id wid,
  7722. pjmedia_vid_dev_fullscreen_flag mode);
  7723. /*
  7724. * Video codecs API
  7725. */
  7726. /**
  7727. * Enum all supported video codecs in the system.
  7728. *
  7729. * @param id Array of ID to be initialized.
  7730. * @param count On input, specifies max elements in the array.
  7731. * On return, it contains actual number of elements
  7732. * that have been initialized.
  7733. *
  7734. * @return PJ_SUCCESS on success, or the appropriate error code.
  7735. */
  7736. PJ_DECL(pj_status_t) pjsua_vid_enum_codecs( pjsua_codec_info id[],
  7737. unsigned *count );
  7738. /**
  7739. * Change video codec priority.
  7740. *
  7741. * @param codec_id Codec ID, which is a string that uniquely identify
  7742. * the codec (such as "H263/90000"). Please see pjsua
  7743. * manual or pjmedia codec reference for details.
  7744. * @param priority Codec priority, 0-255, where zero means to disable
  7745. * the codec.
  7746. *
  7747. * @return PJ_SUCCESS on success, or the appropriate error code.
  7748. */
  7749. PJ_DECL(pj_status_t) pjsua_vid_codec_set_priority( const pj_str_t *codec_id,
  7750. pj_uint8_t priority );
  7751. /**
  7752. * Get video codec parameters.
  7753. *
  7754. * @param codec_id Codec ID.
  7755. * @param param Structure to receive video codec parameters.
  7756. *
  7757. * @return PJ_SUCCESS on success, or the appropriate error code.
  7758. */
  7759. PJ_DECL(pj_status_t) pjsua_vid_codec_get_param(
  7760. const pj_str_t *codec_id,
  7761. pjmedia_vid_codec_param *param);
  7762. /**
  7763. * Set video codec parameters.
  7764. *
  7765. * @param codec_id Codec ID.
  7766. * @param param Codec parameter to set. Set to NULL to reset
  7767. * codec parameter to library default settings.
  7768. *
  7769. * @return PJ_SUCCESS on success, or the appropriate error code.
  7770. */
  7771. PJ_DECL(pj_status_t) pjsua_vid_codec_set_param(
  7772. const pj_str_t *codec_id,
  7773. const pjmedia_vid_codec_param *param);
  7774. /*
  7775. * Video conference API
  7776. */
  7777. /**
  7778. * This structure describes information about a particular video media port
  7779. * that has been registered into the video conference bridge. Application
  7780. * can query this info by calling #pjsua_vid_conf_get_port_info().
  7781. */
  7782. typedef struct pjsua_vid_conf_port_info
  7783. {
  7784. /** Conference port number. */
  7785. pjsua_conf_port_id slot_id;
  7786. /** Port name. */
  7787. pj_str_t name;
  7788. /** Format. */
  7789. pjmedia_format format;
  7790. /** Number of listeners in the array. */
  7791. unsigned listener_cnt;
  7792. /** Array of listeners (in other words, ports where this port is
  7793. * transmitting to).
  7794. */
  7795. pjsua_conf_port_id listeners[PJSUA_MAX_CONF_PORTS];
  7796. /** Number of transmitters in the array. */
  7797. unsigned transmitter_cnt;
  7798. /** Array of transmitters (in other words, ports where this port is
  7799. * receiving from).
  7800. */
  7801. pjsua_conf_port_id transmitters[PJSUA_MAX_CONF_PORTS];
  7802. } pjsua_vid_conf_port_info;
  7803. /**
  7804. * Get current number of active ports in the bridge.
  7805. *
  7806. * @return The number.
  7807. */
  7808. PJ_DECL(unsigned) pjsua_vid_conf_get_active_ports(void);
  7809. /**
  7810. * Enumerate all video conference ports.
  7811. *
  7812. * @param id Array of conference port ID to be initialized.
  7813. * @param count On input, specifies max elements in the array.
  7814. * On return, it contains actual number of elements
  7815. * that have been initialized.
  7816. *
  7817. * @return PJ_SUCCESS on success, or the appropriate error code.
  7818. */
  7819. PJ_DECL(pj_status_t) pjsua_vid_conf_enum_ports(pjsua_conf_port_id id[],
  7820. unsigned *count);
  7821. /**
  7822. * Get information about the specified video conference port
  7823. *
  7824. * @param port_id Port identification.
  7825. * @param info Pointer to store the port info.
  7826. *
  7827. * @return PJ_SUCCESS on success, or the appropriate error code.
  7828. */
  7829. PJ_DECL(pj_status_t) pjsua_vid_conf_get_port_info(
  7830. pjsua_conf_port_id port_id,
  7831. pjsua_vid_conf_port_info *info);
  7832. /**
  7833. * Add arbitrary video media port to PJSUA's video conference bridge.
  7834. * Application can use this function to add the media port that it creates.
  7835. * For media ports that are created by PJSUA-LIB (such as calls, AVI player),
  7836. * PJSUA-LIB will automatically add the port to the bridge.
  7837. *
  7838. * @param pool Pool to use.
  7839. * @param port Media port to be added to the bridge.
  7840. * @param param Currently this is not used and must be set to NULL.
  7841. * @param p_id Optional pointer to receive the conference
  7842. * slot id.
  7843. *
  7844. * @return PJ_SUCCESS on success, or the appropriate error code.
  7845. */
  7846. PJ_DECL(pj_status_t) pjsua_vid_conf_add_port(pj_pool_t *pool,
  7847. pjmedia_port *port,
  7848. const void *param,
  7849. pjsua_conf_port_id *p_id);
  7850. /**
  7851. * Remove arbitrary slot from the video conference bridge. Application should
  7852. * only call this function if it registered the port manually with previous
  7853. * call to #pjsua_vid_conf_add_port().
  7854. *
  7855. * @param port_id The slot id of the port to be removed.
  7856. *
  7857. * @return PJ_SUCCESS on success, or the appropriate error code.
  7858. */
  7859. PJ_DECL(pj_status_t) pjsua_vid_conf_remove_port(pjsua_conf_port_id port_id);
  7860. /**
  7861. * Establish unidirectional video flow from souce to sink. One source
  7862. * may transmit to multiple destinations/sink. And if multiple
  7863. * sources are transmitting to the same sink, the video will be mixed
  7864. * together (currently, each source will be resized down so all sources will
  7865. * occupy the same portion in the sink video frame). Source and sink may
  7866. * refer to the same ID, effectively looping the media.
  7867. *
  7868. * If bidirectional media flow is desired, application needs to call
  7869. * this function twice, with the second one having the arguments
  7870. * reversed.
  7871. *
  7872. * @param source Port ID of the source media/transmitter.
  7873. * @param sink Port ID of the destination media/received.
  7874. * @param param Currently this is not used and must be set to NULL.
  7875. *
  7876. * @return PJ_SUCCESS on success, or the appropriate error code.
  7877. */
  7878. PJ_DECL(pj_status_t) pjsua_vid_conf_connect(pjsua_conf_port_id source,
  7879. pjsua_conf_port_id sink,
  7880. const void *param);
  7881. /**
  7882. * Disconnect video flow from the source to destination port.
  7883. *
  7884. * @param source Port ID of the source media/transmitter.
  7885. * @param sink Port ID of the destination media/received.
  7886. *
  7887. * @return PJ_SUCCESS on success, or the appropriate error code.
  7888. */
  7889. PJ_DECL(pj_status_t) pjsua_vid_conf_disconnect(pjsua_conf_port_id source,
  7890. pjsua_conf_port_id sink);
  7891. /**
  7892. * Update or refresh port states from video port info. Some port may
  7893. * change its port info in the middle of a session, for example when
  7894. * a video stream decoder learns that incoming video size or frame rate
  7895. * has changed, video conference needs to be informed to update its
  7896. * internal states.
  7897. *
  7898. * @param port_id The slot id of the port to be updated.
  7899. *
  7900. * @return PJ_SUCCESS on success, or the appropriate error
  7901. * code.
  7902. */
  7903. PJ_DECL(pj_status_t) pjsua_vid_conf_update_port(pjsua_conf_port_id port_id);
  7904. /* end of VIDEO API */
  7905. /**
  7906. * @}
  7907. */
  7908. /**
  7909. * @}
  7910. */
  7911. PJ_END_DECL
  7912. #endif /* __PJSUA_H__ */