1 /* 2 * This file is part of the Sofia-SIP package 3 * 4 * Copyright (C) 2005 Nokia Corporation. 5 * 6 * Contact: Pekka Pessi <pekka.pessi@nokia.com> 7 * 8 * This library is free software; you can redistribute it and/or 9 * modify it under the terms of the GNU Lesser General Public License 10 * as published by the Free Software Foundation; either version 2.1 of 11 * the License, or (at your option) any later version. 12 * 13 * This library is distributed in the hope that it will be useful, but 14 * WITHOUT ANY WARRANTY; without even the implied warranty of 15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 16 * Lesser General Public License for more details. 17 * 18 * You should have received a copy of the GNU Lesser General Public 19 * License along with this library; if not, write to the Free Software 20 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 21 * 02110-1301 USA 22 * 23 */ 24 25 #ifndef TPORT_H 26 /** Defined when <sofia-sip/tport.h> has been included. */ 27 #define TPORT_H 28 /**@file sofia-sip/tport.h 29 * @brief Transport interface 30 * 31 * @author Pekka Pessi <Pekka.Pessi@nokia.com> 32 * 33 * @date Created: Thu Jun 29 15:58:06 2000 ppessi 34 */ 35 36 #ifndef SU_H 37 #include <sofia-sip/su.h> 38 #endif 39 #ifndef SU_STRLST_H 40 #include <sofia-sip/su_strlst.h> 41 #endif 42 #ifndef SU_WAIT_H 43 #include <sofia-sip/su_wait.h> 44 #endif 45 #ifndef MSG_H 46 #include <sofia-sip/msg.h> 47 #endif 48 #ifndef URL_H 49 #include <sofia-sip/url.h> 50 #endif 51 #ifndef TPORT_TAG_H 52 #include <sofia-sip/tport_tag.h> 53 #endif 54 55 SOFIA_BEGIN_DECLS 56 57 struct tport_s; 58 #ifndef TPORT_T 59 #define TPORT_T struct tport_s 60 typedef TPORT_T tport_t; 61 #endif 62 63 #ifndef TP_STACK_T 64 #ifndef TP_AGENT_T 65 #define TP_STACK_T struct tp_stack_s 66 #else 67 #define TP_STACK_T TP_AGENT_T 68 #endif 69 #endif 70 /** Type of stack object */ 71 typedef TP_STACK_T tp_stack_t; 72 73 #ifndef TP_MAGIC_T 74 /** Type of transport-protocol-specific context. @sa @ref tp_magic */ 75 #define TP_MAGIC_T struct tp_magic_s 76 #endif 77 /** Type of transport-protocol-specific context object. */ 78 typedef TP_MAGIC_T tp_magic_t; 79 80 #ifndef TP_CLIENT_T 81 #define TP_CLIENT_T struct tp_client_s 82 #endif 83 /** Transaction object given as a reference to the transport. 84 * 85 * This type is used when transport reports errors with pending requests. 86 */ 87 typedef TP_CLIENT_T tp_client_t; 88 89 struct sigcomp_compartment; 90 struct sigcomp_udvm; 91 92 /** Interface towards stack. */ 93 typedef struct { 94 int tpac_size; 95 96 /** Function used to pass a received message to the protocol stack */ 97 void (*tpac_recv)(tp_stack_t *, tport_t *, msg_t *msg, tp_magic_t *magic, 98 su_time_t received); 99 100 /** Function used to indicate an error to the protocol stack */ 101 void (*tpac_error)(tp_stack_t *, tport_t *, 102 int errcode, char const *remote); 103 104 /** Ask stack to allocate a message. */ 105 msg_t *(*tpac_alloc)(tp_stack_t *, int flags, 106 char const [], usize_t, 107 tport_t const *, tp_client_t *); 108 109 /** Indicate stack that address has changed */ 110 void (*tpac_address)(tp_stack_t *, tport_t *); 111 112 } tport_stack_class_t; 113 114 /* Compatibility */ 115 typedef tport_stack_class_t tp_stack_class_t; 116 117 /** Callback to report error by pending requests. */ 118 typedef void tport_pending_error_f(tp_stack_t *, tp_client_t *, 119 tport_t *, msg_t *msg, int error); 120 121 enum { 122 /** Maximum number of messages in send queue. */ 123 TPORT_QUEUESIZE = 64 124 }; 125 126 127 /* AI extension flags - these must not overlap with existing AI flags. */ 128 129 /** Message is to be sent/received compressed */ 130 #define TP_AI_COMPRESSED 0x01000 131 /** Message is to be sent/received on secure connection */ 132 #define TP_AI_SECURE 0x02000 133 134 /** Halfclose (shutdown(c, 1)) connection after sending message */ 135 #define TP_AI_SHUTDOWN 0x04000 136 /** Close connection (shutdown(c, 2)) after sending message */ 137 #define TP_AI_CLOSE 0x08000 138 139 /** Address was inaddr_any */ 140 #define TP_AI_ANY 0x80000 141 142 #define TP_AI_MASK 0xff000 143 144 /** Maximum size of a @e host:port string, including final NUL. */ 145 #define TPORT_HOSTPORTSIZE (55) 146 147 /** Transport name. 148 * 149 * This structure represents the address of the transport in textual format. 150 * For primary transports, the transport name contains the local address, 151 * for secondary transports, the peer address. 152 * 153 * The tpn_ident specifies the transport identifier used to make difference 154 * between connectivity domains. 155 */ 156 typedef struct { 157 char const *tpn_proto; /**< Protocol name ("udp", "tcp", etc.) */ 158 char const *tpn_canon; /**< Node DNS name (if known). */ 159 char const *tpn_host; /**< Node address in textual format */ 160 char const *tpn_port; /**< Port number in textual format. */ 161 char const *tpn_comp; /**< Compression algorithm (NULL if none) */ 162 char const *tpn_ident; /**< Transport identifier (NULL if none) */ 163 } tp_name_t; 164 165 #define TPN_FORMAT "%s/%s:%s%s%s%s%s" 166 167 #define TPN_ARGS(n) \ 168 (n)->tpn_proto, (n)->tpn_host, (n)->tpn_port, \ 169 (n)->tpn_comp ? ";comp=" : "", (n)->tpn_comp ? (n)->tpn_comp : "", \ 170 (n)->tpn_ident ? "/" : "", (n)->tpn_ident ? (n)->tpn_ident : "" 171 172 /**Create master transport. */ 173 TPORT_DLL tport_t *tport_tcreate(tp_stack_t *stack, 174 tport_stack_class_t const *tpac, 175 su_root_t *root, 176 tag_type_t tag, tag_value_t value, ...); 177 178 /** Bind transports to network. */ 179 TPORT_DLL int tport_tbind(tport_t *self, 180 tp_name_t const *tpn, 181 char const * const transports[], 182 tag_type_t tag, tag_value_t value, ...); 183 184 /** Get transport parameters. */ 185 TPORT_DLL int tport_get_params(tport_t const *, tag_type_t tag, tag_value_t value, ...); 186 187 /** Set transport parameters. */ 188 TPORT_DLL int tport_set_params(tport_t *self, tag_type_t tag, tag_value_t value, ...); 189 190 /** Destroy transport(s). */ 191 TPORT_DLL void tport_destroy(tport_t *tport); 192 193 /** Shutdown a transport connection. */ 194 TPORT_DLL int tport_shutdown(tport_t *tport, int how); 195 196 /** Create a new reference to a transport object. */ 197 TPORT_DLL tport_t *tport_ref(tport_t *tp); 198 199 /** Destroy reference to a transport object. */ 200 TPORT_DLL void tport_unref(tport_t *tp); 201 202 /** Create a new transport reference. @deprecated Use tport_ref(). */ 203 TPORT_DLL tport_t *tport_incref(tport_t *tp); 204 205 /** Destroy a transport reference. @deprecated Use tport_unref(). */ 206 TPORT_DLL void tport_decref(tport_t **tp); 207 208 /** Send a message using transport. */ 209 TPORT_DLL tport_t *tport_tsend(tport_t *, msg_t *, tp_name_t const *, 210 tag_type_t, tag_value_t, ...); 211 212 /** Queue a message to transport. */ 213 TPORT_DLL int tport_tqueue(tport_t *, msg_t *, tag_type_t, tag_value_t, ...); 214 215 /** Return number of queued messages. */ 216 TPORT_DLL isize_t tport_queuelen(tport_t const *self); 217 218 /** Send a queued message (and queue another, if required). */ 219 TPORT_DLL int tport_tqsend(tport_t *, msg_t *, msg_t *, 220 tag_type_t, tag_value_t, ...); 221 222 /** Stop reading from socket until tport_continue() is called. */ 223 TPORT_DLL int tport_stall(tport_t *self); 224 225 /** Continue reading from socket. */ 226 TPORT_DLL int tport_continue(tport_t *self); 227 228 /** Mark message as waiting for a response. */ 229 TPORT_DLL int tport_pend(tport_t *self, msg_t *msg, 230 tport_pending_error_f *callback, tp_client_t *client); 231 232 /** Do not wait for response anymore. */ 233 TPORT_DLL int tport_release(tport_t *self, int pendd, 234 msg_t *msg, msg_t *reply, tp_client_t *client, 235 int still_pending); 236 237 /** Return true if transport is master. */ 238 TPORT_DLL int tport_is_master(tport_t const *self); 239 240 /** Return true if transport is primary. */ 241 TPORT_DLL int tport_is_primary(tport_t const *self); 242 243 /** Return nonzero if transport is public. */ 244 TPORT_DLL int tport_is_public(tport_t const *self); 245 246 /** Return true if transport is secondary. */ 247 TPORT_DLL int tport_is_secondary(tport_t const *self); 248 249 /** Return true if transport is reliable, false otherwise */ 250 TPORT_DLL int tport_is_reliable(tport_t const *tport); 251 252 /** Return true if transport is a stream (no message boundaries). */ 253 TPORT_DLL int tport_is_stream(tport_t const *tport); 254 255 /** Return true if transport is dgram-based. */ 256 TPORT_DLL int tport_is_dgram(tport_t const *tport); 257 258 /** Return true if transport supports IPv4 */ 259 TPORT_DLL int tport_has_ip4(tport_t const *tport); 260 261 /** Return true if transport supports IPv6 */ 262 TPORT_DLL int tport_has_ip6(tport_t const *tport); 263 264 /** Test if transport is udp. */ 265 TPORT_DLL int tport_is_udp(tport_t const *self); 266 267 /** Test if transport is tcp. */ 268 TPORT_DLL int tport_is_tcp(tport_t const *self); 269 270 /** Test if transport has TLS. */ 271 TPORT_DLL int tport_has_tls(tport_t const *tport); 272 273 /** Test if transport provided a verified certificate chain (TLS only) */ 274 TPORT_DLL int tport_is_verified(tport_t const *tport); 275 276 /** Return true if transport is being updated. */ 277 TPORT_DLL int tport_is_updating(tport_t const *self); 278 279 /** Test if transport has been closed. @NEW_1_12_4. */ 280 TPORT_DLL int tport_is_closed(tport_t const *self); 281 282 /** Test if transport has been shut down. @NEW_1_12_4. */ 283 TPORT_DLL int tport_is_shutdown(tport_t const *self); 284 285 /** Test if transport is connected. @NEW_1_12_5. */ 286 TPORT_DLL int tport_is_connected(tport_t const *self); 287 288 /** Test if transport can be used to send message. @NEW_1_12_7. */ 289 TPORT_DLL int tport_is_clear_to_send(tport_t const *self); 290 291 /** Set transport magic. */ 292 TPORT_DLL void tport_set_magic(tport_t *self, tp_magic_t *magic); 293 294 /** Get transport magic. */ 295 TPORT_DLL tp_magic_t *tport_magic(tport_t const *tport); 296 297 /** Get transport name. */ 298 TPORT_DLL tp_name_t const *tport_name(tport_t const *tport); 299 300 /** Get transport address list. */ 301 TPORT_DLL su_addrinfo_t const *tport_get_address(tport_t const *tport); 302 303 /** Get transport ident. */ 304 TPORT_DLL char const *tport_ident(tport_t const *self); 305 306 /** Get primary transport (or self, if already parent) */ 307 TPORT_DLL tport_t *tport_parent(tport_t const *self); 308 309 /** Flush idle connections */ 310 TPORT_DLL int tport_flush(tport_t *); 311 312 /** Get primary transports */ 313 TPORT_DLL tport_t *tport_primaries(tport_t const *tport); 314 315 /** Get next transport */ 316 TPORT_DLL tport_t *tport_next(tport_t const *tport); 317 318 /** Get secondary transports. */ 319 TPORT_DLL tport_t *tport_secondary(tport_t const *tport); 320 321 /** Get a protocol corresponding to the protocol name. */ 322 TPORT_DLL tport_t *tport_by_protocol(tport_t const *self, char const *proto); 323 324 /** Get transport by interface identifier and protocol name. */ 325 TPORT_DLL tport_t *tport_primary_by_name(tport_t const *self, tp_name_t const *tpn); 326 327 /** Get a transport corresponding to the name */ 328 TPORT_DLL tport_t *tport_by_name(tport_t const *self, tp_name_t const *); 329 330 /** Create a transport name corresponding to the URL. */ 331 TPORT_DLL int tport_name_by_url(su_home_t *, tp_name_t *, 332 url_string_t const *us); 333 334 /** Return source transport object for delivered message */ 335 TPORT_DLL tport_t *tport_delivered_by(tport_t const *tp, msg_t const *msg); 336 337 /** Return source transport name for delivered message */ 338 TPORT_DLL int tport_delivered_from(tport_t *tp, msg_t const *msg, 339 tp_name_t name[1]); 340 341 /** Return TLS Subjects provided by the source transport */ 342 TPORT_DLL su_strlst_t const *tport_delivered_from_subjects(tport_t *tp, 343 msg_t const *msg); 344 345 /** Check if the given subject string is found in su_strlst_t */ 346 TPORT_DLL int tport_subject_search(char const *, su_strlst_t const *); 347 348 /** Check if transport named is already resolved */ 349 TPORT_DLL int tport_name_is_resolved(tp_name_t const *); 350 351 /** Duplicate a transport name. */ 352 TPORT_DLL int tport_name_dup(su_home_t *, 353 tp_name_t *dst, tp_name_t const *src); 354 355 /** Convert a socket address to a transport name. */ 356 TPORT_DLL int tport_convert_addr(su_home_t *home, 357 tp_name_t *tpn, 358 char const *protoname, 359 char const *canon, 360 su_sockaddr_t const *su); 361 362 /** Print host and port separated with ':' to a string. */ 363 TPORT_DLL char *tport_hostport(char buf[], isize_t bufsize, 364 su_sockaddr_t const *su, int with_port); 365 366 /** Initialize STUN keepalives. */ 367 TPORT_DLL int tport_keepalive(tport_t *tp, su_addrinfo_t const *ai, 368 tag_type_t tag, tag_value_t value, ...); 369 370 /* ---------------------------------------------------------------------- */ 371 /* SigComp-related functions */ 372 373 #ifndef TPORT_COMPRESSOR 374 #define TPORT_COMPRESSOR struct tport_compressor 375 #endif 376 377 typedef TPORT_COMPRESSOR tport_compressor_t; 378 379 TPORT_DLL int tport_can_send_sigcomp(tport_t const *self); 380 TPORT_DLL int tport_can_recv_sigcomp(tport_t const *self); 381 382 TPORT_DLL int tport_has_compression(tport_t const *self, char const *comp); 383 TPORT_DLL int tport_set_compression(tport_t *self, char const *comp); 384 385 /** Set SigComp option. */ 386 TPORT_DLL 387 int tport_sigcomp_option(tport_t const *self, 388 struct sigcomp_compartment *cc, 389 char const *option); 390 391 /** Obtain a SigComp compartment with given name. */ 392 TPORT_DLL struct sigcomp_compartment * 393 tport_sigcomp_compartment(tport_t *self, 394 char const *name, isize_t namelen, 395 int create_if_needed); 396 397 /** Assign a SigComp compartment to a connection-oriented tport. */ 398 TPORT_DLL int 399 tport_sigcomp_assign(tport_t *self, struct sigcomp_compartment *); 400 401 /** Test if a SigComp compartment is assigned to a tport. */ 402 TPORT_DLL int tport_has_sigcomp_assigned(tport_t const *self); 403 404 /** Accept SigComp message */ 405 TPORT_DLL int 406 tport_sigcomp_accept(tport_t *self, 407 struct sigcomp_compartment *cc, 408 msg_t *msg); 409 410 /** Get compressor context with which the request was delivered */ 411 TPORT_DLL int 412 tport_delivered_with_comp(tport_t *tp, msg_t const *msg, 413 tport_compressor_t **return_compressor); 414 415 /** Shutdown SigComp compartment */ 416 TPORT_DLL int 417 tport_sigcomp_close(tport_t *self, 418 struct sigcomp_compartment *cc, 419 int how); 420 421 /** Set SigComp compartment lifetime. */ 422 TPORT_DLL int 423 tport_sigcomp_lifetime(tport_t *self, 424 struct sigcomp_compartment *, 425 unsigned lifetime_in_ms, 426 int only_expand); 427 428 429 SOFIA_END_DECLS 430 431 #endif /* TPORT_H */ 432