sofia-sip/nta.h
Go to the documentation of this file.
00001 /* 00002 * This file is part of the Sofia-SIP package 00003 * 00004 * Copyright (C) 2005 Nokia Corporation. 00005 * 00006 * Contact: Pekka Pessi <pekka.pessi@nokia-email.address.hidden> 00007 * 00008 * This library is free software; you can redistribute it and/or 00009 * modify it under the terms of the GNU Lesser General Public License 00010 * as published by the Free Software Foundation; either version 2.1 of 00011 * the License, or (at your option) any later version. 00012 * 00013 * This library is distributed in the hope that it will be useful, but 00014 * WITHOUT ANY WARRANTY; without even the implied warranty of 00015 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 00016 * Lesser General Public License for more details. 00017 * 00018 * You should have received a copy of the GNU Lesser General Public 00019 * License along with this library; if not, write to the Free Software 00020 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 00021 * 02110-1301 USA 00022 * 00023 */ 00024 00025 #ifndef NTA_H 00026 00027 #define NTA_H 00028 00036 #ifndef SU_WAIT_H 00037 #include <sofia-sip/su_wait.h> 00038 #endif 00039 00040 #ifndef SIP_H 00041 #include <sofia-sip/sip.h> 00042 #endif 00043 00044 #ifndef NTA_TAG_H 00045 #include <sofia-sip/nta_tag.h> 00046 #endif 00047 00048 SOFIA_BEGIN_DECLS 00049 00050 /* ---------------------------------------------------------------------- 00051 * 1) Types 00052 */ 00053 00055 typedef struct nta_agent_s nta_agent_t; 00057 typedef struct nta_leg_s nta_leg_t; 00059 typedef struct nta_outgoing_s nta_outgoing_t; 00061 typedef struct nta_incoming_s nta_incoming_t; 00062 00063 #ifndef NTA_AGENT_MAGIC_T 00064 00067 #define NTA_AGENT_MAGIC_T struct nta_agent_magic_s 00068 #endif 00069 #ifndef NTA_LEG_MAGIC_T 00070 00073 #define NTA_LEG_MAGIC_T struct nta_leg_magic_s 00074 #endif 00075 #ifndef NTA_OUTGOING_MAGIC_T 00076 00079 #define NTA_OUTGOING_MAGIC_T struct nta_outgoing_magic_s 00080 #endif 00081 #ifndef NTA_INCOMING_MAGIC_T 00082 00085 #define NTA_INCOMING_MAGIC_T struct nta_incoming_magic_s 00086 #endif 00087 00089 typedef NTA_AGENT_MAGIC_T nta_agent_magic_t; 00091 typedef NTA_LEG_MAGIC_T nta_leg_magic_t; 00093 typedef NTA_OUTGOING_MAGIC_T nta_outgoing_magic_t; 00095 typedef NTA_INCOMING_MAGIC_T nta_incoming_magic_t; 00096 00097 /* ---------------------------------------------------------------------- 00098 * 2) Constants 00099 */ 00100 00102 #define NTA_VERSION "2.0" 00103 00105 SOFIAPUBVAR char const nta_version[]; 00106 00107 enum { 00108 /* Stack parameters */ 00109 NTA_SIP_T1 = 500, 00110 NTA_SIP_T2 = 4000, 00111 NTA_SIP_T4 = 5000, 00112 NTA_TIME_MAX = 15 * 24 * 3600 * 1000 00114 }; 00115 00116 /* ---------------------------------------------------------------------- 00117 * 3) Agent-level prototypes 00118 */ 00119 00120 typedef int nta_message_f(nta_agent_magic_t *context, 00121 nta_agent_t *agent, 00122 msg_t *msg, 00123 sip_t *sip); 00124 00125 SOFIAPUBFUN 00126 nta_agent_t *nta_agent_create(su_root_t *root, 00127 url_string_t const *name, 00128 nta_message_f *callback, 00129 nta_agent_magic_t *magic, 00130 tag_type_t tag, tag_value_t value, ...); 00131 00132 SOFIAPUBFUN void nta_agent_destroy(nta_agent_t *agent); 00133 00134 SOFIAPUBFUN char const *nta_agent_version(nta_agent_t const *a); 00135 SOFIAPUBFUN nta_agent_magic_t *nta_agent_magic(nta_agent_t const *a); 00136 00137 SOFIAPUBFUN 00138 int nta_agent_add_tport(nta_agent_t *agent, 00139 url_string_t const *url, 00140 tag_type_t tag, tag_value_t value, ...); 00141 00142 SOFIAPUBFUN int nta_agent_close_tports(nta_agent_t *agent); 00143 00144 SOFIAPUBFUN sip_contact_t *nta_agent_contact(nta_agent_t const *a); 00145 SOFIAPUBFUN sip_via_t *nta_agent_via(nta_agent_t const *a); 00146 SOFIAPUBFUN sip_via_t *nta_agent_public_via(nta_agent_t const *a); 00147 00148 SOFIAPUBFUN char const *nta_agent_newtag(su_home_t *, 00149 char const *fmt, nta_agent_t *); 00150 00151 SOFIAPUBFUN int nta_agent_set_params(nta_agent_t *agent, 00152 tag_type_t tag, tag_value_t value, ...); 00153 SOFIAPUBFUN int nta_agent_get_params(nta_agent_t *agent, 00154 tag_type_t tag, tag_value_t value, ...); 00155 00156 SOFIAPUBFUN int nta_agent_get_stats(nta_agent_t *agent, 00157 tag_type_t tag, tag_value_t value, ...); 00158 00159 /* ---------------------------------------------------------------------- 00160 * 4) Message-level prototypes 00161 */ 00162 00163 SOFIAPUBFUN msg_t *nta_msg_create(nta_agent_t *self, int flags); 00164 00165 SOFIAPUBFUN int nta_msg_complete(msg_t *msg); 00166 00167 SOFIAPUBFUN int nta_msg_request_complete(msg_t *msg, 00168 nta_leg_t *leg, 00169 sip_method_t method, 00170 char const *method_name, 00171 url_string_t const *req_url); 00172 00173 SOFIAPUBFUN int nta_msg_is_internal(msg_t const *msg); 00174 SOFIAPUBFUN int nta_sip_is_internal(sip_t const *sip); 00175 00176 /* ---------------------------------------------------------------------- 00177 * 5) Leg-level prototypes 00178 */ 00179 typedef int nta_request_f(nta_leg_magic_t *lmagic, 00180 nta_leg_t *leg, 00181 nta_incoming_t *irq, 00182 sip_t const *sip); 00183 00184 SOFIAPUBFUN 00185 nta_leg_t *nta_leg_tcreate(nta_agent_t *agent, 00186 nta_request_f *req_callback, 00187 nta_leg_magic_t *magic, 00188 tag_type_t tag, tag_value_t value, ...); 00189 00190 SOFIAPUBFUN void nta_leg_destroy(nta_leg_t *leg); 00191 00192 SOFIAPUBFUN nta_leg_t *nta_default_leg(nta_agent_t const *agent); 00193 00194 SOFIAPUBFUN nta_leg_magic_t *nta_leg_magic(nta_leg_t const *leg, 00195 nta_request_f *callback); 00196 00197 SOFIAPUBFUN void nta_leg_bind(nta_leg_t *leg, 00198 nta_request_f *callback, 00199 nta_leg_magic_t *); 00200 00202 SOFIAPUBFUN char const *nta_leg_tag(nta_leg_t *leg, char const *tag); 00203 00205 SOFIAPUBFUN char const *nta_leg_get_tag(nta_leg_t const *leg); 00206 00208 SOFIAPUBFUN char const *nta_leg_rtag(nta_leg_t *leg, char const *tag); 00209 00211 SOFIAPUBFUN char const *nta_leg_get_rtag(nta_leg_t const *leg); 00212 00214 SOFIAPUBFUN uint32_t nta_leg_get_seq(nta_leg_t const *leg); 00215 00217 SOFIAPUBFUN uint32_t nta_leg_get_rseq(nta_leg_t const *leg); 00218 00219 SOFIAPUBFUN int nta_leg_client_route(nta_leg_t *leg, 00220 sip_record_route_t const *route, 00221 sip_contact_t const *contact); 00222 00223 SOFIAPUBFUN int nta_leg_client_reroute(nta_leg_t *leg, 00224 sip_record_route_t const *route, 00225 sip_contact_t const *contact, 00226 int initial); 00227 00228 SOFIAPUBFUN int nta_leg_server_route(nta_leg_t *leg, 00229 sip_record_route_t const *route, 00230 sip_contact_t const *contact); 00231 00233 SOFIAPUBFUN int nta_leg_get_route(nta_leg_t *leg, 00234 sip_route_t const **return_route, 00235 sip_contact_t const **return_target); 00236 00238 SOFIAPUBFUN nta_leg_t *nta_leg_by_uri(nta_agent_t const *, 00239 url_string_t const *); 00240 00242 SOFIAPUBFUN 00243 nta_leg_t *nta_leg_by_dialog(nta_agent_t const *agent, 00244 url_t const *request_uri, 00245 sip_call_id_t const *call_id, 00246 char const *from_tag, 00247 url_t const *from_url, 00248 char const *to_tag, 00249 url_t const *to_url); 00250 00252 SOFIAPUBFUN sip_replaces_t *nta_leg_make_replaces(nta_leg_t *leg, 00253 su_home_t *home, 00254 int early_only); 00256 SOFIAPUBFUN 00257 nta_leg_t *nta_leg_by_replaces(nta_agent_t *, sip_replaces_t const *); 00258 00260 SOFIAPUBFUN 00261 nta_leg_t *nta_leg_by_call_id(nta_agent_t *sa, const char *call_id); 00262 00263 /* ---------------------------------------------------------------------- 00264 * 6) Prototypes for incoming transactions 00265 */ 00266 00267 SOFIAPUBFUN 00268 nta_incoming_t *nta_incoming_create(nta_agent_t *agent, 00269 nta_leg_t *leg, 00270 msg_t *msg, 00271 sip_t *sip, 00272 tag_type_t tag, tag_value_t value, ...); 00273 00274 SOFIAPUBFUN nta_incoming_t *nta_incoming_default(nta_agent_t *agent); 00275 00276 typedef int nta_ack_cancel_f(nta_incoming_magic_t *imagic, 00277 nta_incoming_t *irq, 00278 sip_t const *sip); 00279 00280 SOFIAPUBFUN void nta_incoming_bind(nta_incoming_t *irq, 00281 nta_ack_cancel_f *callback, 00282 nta_incoming_magic_t *imagic); 00283 00284 SOFIAPUBFUN 00285 nta_incoming_magic_t *nta_incoming_magic(nta_incoming_t *irq, 00286 nta_ack_cancel_f *callback); 00287 00288 SOFIAPUBFUN 00289 nta_incoming_t *nta_incoming_find(nta_agent_t const *agent, 00290 sip_t const *sip, 00291 sip_via_t const *v); 00292 00293 SOFIAPUBFUN char const *nta_incoming_tag(nta_incoming_t *irq, char const *tag); 00294 SOFIAPUBFUN char const *nta_incoming_gettag(nta_incoming_t const *irq); 00295 00296 SOFIAPUBFUN int nta_incoming_status(nta_incoming_t const *irq); 00297 SOFIAPUBFUN sip_method_t nta_incoming_method(nta_incoming_t const *irq); 00298 SOFIAPUBFUN char const *nta_incoming_method_name(nta_incoming_t const *irq); 00299 SOFIAPUBFUN url_t const *nta_incoming_url(nta_incoming_t const *irq); 00300 SOFIAPUBFUN uint32_t nta_incoming_cseq(nta_incoming_t const *irq); 00301 SOFIAPUBFUN sip_time_t nta_incoming_received(nta_incoming_t *irq, su_nanotime_t *nano); 00302 00303 SOFIAPUBFUN int nta_incoming_set_params(nta_incoming_t *irq, 00304 tag_type_t tag, tag_value_t value, ...); 00305 00306 SOFIAPUBFUN msg_t *nta_incoming_getrequest(nta_incoming_t *irq); 00307 SOFIAPUBFUN msg_t *nta_incoming_getrequest_ackcancel(nta_incoming_t *irq); 00308 SOFIAPUBFUN msg_t *nta_incoming_getresponse(nta_incoming_t *irq); 00309 00310 SOFIAPUBFUN 00311 int nta_incoming_complete_response(nta_incoming_t *irq, 00312 msg_t *msg, 00313 int status, 00314 char const *phrase, 00315 tag_type_t tag, tag_value_t value, ...); 00316 00317 SOFIAPUBFUN 00318 msg_t *nta_incoming_create_response(nta_incoming_t *irq, int status, char const *phrase); 00319 00320 SOFIAPUBFUN 00321 int nta_incoming_treply(nta_incoming_t *ireq, 00322 int status, char const *phrase, 00323 tag_type_t tag, tag_value_t value, ...); 00324 00325 SOFIAPUBFUN int nta_incoming_mreply(nta_incoming_t *irq, msg_t *msg); 00326 00327 SOFIAPUBFUN void nta_incoming_destroy(nta_incoming_t *irq); 00328 00329 /* Functions for feature, method, mime, session-timer negotation */ 00330 00331 SOFIAPUBFUN 00332 int nta_check_required(nta_incoming_t *irq, 00333 sip_t const *sip, 00334 sip_supported_t const *supported, 00335 tag_type_t tag, tag_value_t value, ...); 00336 SOFIAPUBFUN 00337 int nta_check_supported(nta_incoming_t *irq, 00338 sip_t const *sip, 00339 sip_require_t *require, 00340 tag_type_t tag, tag_value_t value, ...); 00341 SOFIAPUBFUN 00342 int nta_check_method(nta_incoming_t *irq, 00343 sip_t const *sip, 00344 sip_allow_t const *allow, 00345 tag_type_t tag, tag_value_t value, ...); 00346 SOFIAPUBFUN 00347 int nta_check_session_content(nta_incoming_t *irq, sip_t const *sip, 00348 sip_accept_t const *session_accepts, 00349 tag_type_t tag, tag_value_t value, ...); 00350 SOFIAPUBFUN 00351 int nta_check_accept(nta_incoming_t *irq, 00352 sip_t const *sip, 00353 sip_accept_t const *acceptable, 00354 sip_accept_t const **return_acceptable, 00355 tag_type_t tag, tag_value_t value, ...); 00356 00357 SOFIAPUBFUN 00358 int nta_check_session_expires(nta_incoming_t *irq, 00359 sip_t const *sip, 00360 sip_time_t my_min_se, 00361 tag_type_t tag, tag_value_t value, ...); 00362 00363 /* ---------------------------------------------------------------------- 00364 * 7) Prototypes for outgoing transactions 00365 */ 00366 typedef int nta_response_f(nta_outgoing_magic_t *magic, 00367 nta_outgoing_t *request, 00368 sip_t const *sip); 00369 00370 SOFIAPUBFUN 00371 nta_outgoing_t *nta_outgoing_tcreate(nta_leg_t *leg, 00372 nta_response_f *callback, 00373 nta_outgoing_magic_t *magic, 00374 url_string_t const *route_url, 00375 sip_method_t method, 00376 char const *method_name, 00377 url_string_t const *request_uri, 00378 tag_type_t tag, tag_value_t value, ...); 00379 00380 SOFIAPUBFUN 00381 nta_outgoing_t *nta_outgoing_mcreate(nta_agent_t *agent, 00382 nta_response_f *callback, 00383 nta_outgoing_magic_t *magic, 00384 url_string_t const *route_url, 00385 msg_t *msg, 00386 tag_type_t tag, tag_value_t value, ...); 00387 00388 SOFIAPUBFUN 00389 nta_outgoing_t *nta_outgoing_default(nta_agent_t *agent, 00390 nta_response_f *callback, 00391 nta_outgoing_magic_t *magic); 00392 00393 SOFIAPUBFUN int nta_outgoing_bind(nta_outgoing_t *orq, 00394 nta_response_f *callback, 00395 nta_outgoing_magic_t *magic); 00396 SOFIAPUBFUN nta_outgoing_magic_t *nta_outgoing_magic(nta_outgoing_t const *orq, 00397 nta_response_f *callback); 00398 SOFIAPUBFUN int nta_outgoing_status(nta_outgoing_t const *orq); 00399 SOFIAPUBFUN sip_method_t nta_outgoing_method(nta_outgoing_t const *orq); 00400 SOFIAPUBFUN char const *nta_outgoing_method_name(nta_outgoing_t const *orq); 00401 SOFIAPUBFUN uint32_t nta_outgoing_cseq(nta_outgoing_t const *orq); 00402 SOFIAPUBFUN char const *nta_outgoing_branch(nta_outgoing_t const *orq); 00403 00404 SOFIAPUBFUN unsigned nta_outgoing_delay(nta_outgoing_t const *orq); 00405 00406 SOFIAPUBFUN url_t const *nta_outgoing_request_uri(nta_outgoing_t const *orq); 00407 SOFIAPUBFUN url_t const *nta_outgoing_route_uri(nta_outgoing_t const *orq); 00408 00409 SOFIAPUBFUN msg_t *nta_outgoing_getresponse(nta_outgoing_t *orq); 00410 SOFIAPUBFUN msg_t *nta_outgoing_getrequest(nta_outgoing_t *orq); 00411 00412 SOFIAPUBFUN 00413 nta_outgoing_t *nta_outgoing_tagged(nta_outgoing_t *orq, 00414 nta_response_f *callback, 00415 nta_outgoing_magic_t *magic, 00416 char const *to_tag, 00417 sip_rseq_t const *rseq); 00418 00419 SOFIAPUBFUN int nta_outgoing_cancel(nta_outgoing_t *); 00420 00421 SOFIAPUBFUN 00422 nta_outgoing_t *nta_outgoing_tcancel(nta_outgoing_t *orq, 00423 nta_response_f *callback, 00424 nta_outgoing_magic_t *magic, 00425 tag_type_t, tag_value_t, ...); 00426 00427 SOFIAPUBFUN void nta_outgoing_destroy(nta_outgoing_t *); 00428 00429 SOFIAPUBFUN 00430 nta_outgoing_t *nta_outgoing_find(nta_agent_t const *sa, 00431 msg_t const *msg, 00432 sip_t const *sip, 00433 sip_via_t const *v); 00434 00435 SOFIAPUBFUN int nta_tport_keepalive(nta_outgoing_t *orq); 00436 00437 /* ---------------------------------------------------------------------- 00438 * 8) Reliable provisional responses (100rel) 00439 */ 00440 00441 /* UAC side */ 00442 00443 SOFIAPUBFUN 00444 nta_outgoing_t *nta_outgoing_prack(nta_leg_t *leg, 00445 nta_outgoing_t *oorq, 00446 nta_response_f *callback, 00447 nta_outgoing_magic_t *magic, 00448 url_string_t const *route_url, 00449 sip_t const *response_to_prack, 00450 tag_type_t, tag_value_t, ...); 00451 00452 SOFIAPUBFUN uint32_t nta_outgoing_rseq(nta_outgoing_t const *orq); 00453 SOFIAPUBFUN int nta_outgoing_setrseq(nta_outgoing_t *orq, uint32_t rseq); 00454 00455 /* UAS side */ 00456 00458 typedef struct nta_reliable_s nta_reliable_t; 00459 00460 #ifndef NTA_RELIABLE_MAGIC_T 00461 00464 #define NTA_RELIABLE_MAGIC_T struct nta_reliable_magic_s 00465 #endif 00466 00468 typedef NTA_RELIABLE_MAGIC_T nta_reliable_magic_t; 00469 00470 typedef int nta_prack_f(nta_reliable_magic_t *rmagic, 00471 nta_reliable_t *rel, 00472 nta_incoming_t *prack, 00473 sip_t const *sip); 00474 00475 SOFIAPUBFUN 00476 nta_reliable_t *nta_reliable_treply(nta_incoming_t *ireq, 00477 nta_prack_f *callback, 00478 nta_reliable_magic_t *rmagic, 00479 int status, char const *phrase, 00480 tag_type_t tag, 00481 tag_value_t value, ...); 00482 00483 SOFIAPUBFUN 00484 nta_reliable_t *nta_reliable_mreply(nta_incoming_t *irq, 00485 nta_prack_f *callback, 00486 nta_reliable_magic_t *rmagic, 00487 msg_t *msg); 00488 00489 SOFIAPUBFUN void nta_reliable_destroy(nta_reliable_t *); 00490 00491 /* ---------------------------------------------------------------------- 00492 * Backward-compatibility stuff - going away soon 00493 */ 00494 00495 #define nta_outgoing_tmcreate nta_outgoing_mcreate 00496 #define nta_msg_response_complete(msg, irq, status, phrase) \ 00497 nta_incoming_complete_response((irq), (msg), (status), (phrase), TAG_END()) 00498 00499 SOFIAPUBFUN void nta_msg_discard(nta_agent_t *agent, msg_t *msg); 00500 00501 SOFIAPUBFUN int nta_is_internal_msg(msg_t const *msg); 00502 00503 SOFIA_END_DECLS 00504 00505 #endif