tport.h 13.8 KB
Newer Older
Pekka Pessi's avatar
Pekka Pessi committed
1 2 3 4 5 6 7
/*
 * This file is part of the Sofia-SIP package
 *
 * Copyright (C) 2005 Nokia Corporation.
 *
 * Contact: Pekka Pessi <pekka.pessi@nokia.com>
 *
8
 * This library is free software; you can redistribute it and/or
Pekka Pessi's avatar
Pekka Pessi committed
9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24
 * modify it under the terms of the GNU Lesser General Public License
 * as published by the Free Software Foundation; either version 2.1 of
 * the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
 * 02110-1301 USA
 *
 */

Pekka Pessi's avatar
Pekka Pessi committed
25 26
#ifndef TPORT_H
/** Defined when <sofia-sip/tport.h> has been included. */
Pekka Pessi's avatar
Pekka Pessi committed
27
#define TPORT_H
Pekka Pessi's avatar
Pekka Pessi committed
28
/**@file sofia-sip/tport.h
29
 * @brief Transport interface
Pekka Pessi's avatar
Pekka Pessi committed
30 31 32 33 34 35 36
 *
 * @author Pekka Pessi <Pekka.Pessi@nokia.com>
 *
 * @date Created: Thu Jun 29 15:58:06 2000 ppessi
 */

#ifndef SU_H
37
#include <sofia-sip/su.h>
Pekka Pessi's avatar
Pekka Pessi committed
38
#endif
39 40 41
#ifndef SU_STRLST_H
#include <sofia-sip/su_strlst.h>
#endif
Pekka Pessi's avatar
Pekka Pessi committed
42
#ifndef SU_WAIT_H
43
#include <sofia-sip/su_wait.h>
Pekka Pessi's avatar
Pekka Pessi committed
44 45
#endif
#ifndef MSG_H
46
#include <sofia-sip/msg.h>
Pekka Pessi's avatar
Pekka Pessi committed
47 48
#endif
#ifndef URL_H
49
#include <sofia-sip/url.h>
Pekka Pessi's avatar
Pekka Pessi committed
50
#endif
51 52 53
#ifndef TPORT_TAG_H
#include <sofia-sip/tport_tag.h>
#endif
Pekka Pessi's avatar
Pekka Pessi committed
54

55 56
#include <sys/time.h>

57 58
SOFIA_BEGIN_DECLS

59 60 61 62 63
struct tport_s;
#ifndef TPORT_T
#define TPORT_T struct tport_s
typedef TPORT_T tport_t;
#endif
Pekka Pessi's avatar
Pekka Pessi committed
64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98

#ifndef TP_STACK_T
#ifndef TP_AGENT_T
#define TP_STACK_T struct tp_stack_s
#else
#define TP_STACK_T TP_AGENT_T
#endif
#endif
/** Type of stack object */
typedef TP_STACK_T tp_stack_t;

#ifndef TP_MAGIC_T
/** Type of transport-protocol-specific context.  @sa @ref tp_magic */
#define TP_MAGIC_T struct tp_magic_s
#endif
/** Type of transport-protocol-specific context object. */
typedef TP_MAGIC_T tp_magic_t;

#ifndef TP_CLIENT_T
#define TP_CLIENT_T struct tp_client_s
#endif
/** Transaction object given as a reference to the transport.
 *
 *  This type is used when transport reports errors with pending requests.
 */
typedef TP_CLIENT_T tp_client_t;

struct sigcomp_compartment;
struct sigcomp_udvm;

/** Interface towards stack. */
typedef struct {
  int      tpac_size;

  /** Function used to pass a received message to the protocol stack */
99
  void   (*tpac_recv)(tp_stack_t *, tport_t *, msg_t *msg, tp_magic_t *magic,
Pekka Pessi's avatar
Pekka Pessi committed
100 101 102
		      su_time_t received);

  /** Function used to indicate an error to the protocol stack */
103
  void   (*tpac_error)(tp_stack_t *, tport_t *,
Pekka Pessi's avatar
Pekka Pessi committed
104 105 106
		       int errcode, char const *remote);

  /** Ask stack to allocate a message. */
107
  msg_t *(*tpac_alloc)(tp_stack_t *, int flags,
108
		       char const [], usize_t,
Pekka Pessi's avatar
Pekka Pessi committed
109 110
		       tport_t const *, tp_client_t *);

111 112 113
  /** Indicate stack that address has changed */
  void (*tpac_address)(tp_stack_t *, tport_t *);

114
} tport_stack_class_t;
Pekka Pessi's avatar
Pekka Pessi committed
115 116

/* Compatibility */
117
typedef tport_stack_class_t tp_stack_class_t;
Pekka Pessi's avatar
Pekka Pessi committed
118 119

/** Callback to report error by pending requests. */
120
typedef void tport_pending_error_f(tp_stack_t *, tp_client_t *,
Pekka Pessi's avatar
Pekka Pessi committed
121 122 123 124 125 126 127
				   tport_t *, msg_t *msg, int error);

enum {
  /** Maximum number of messages in send queue. */
  TPORT_QUEUESIZE = 64
};

128

Pekka Pessi's avatar
Pekka Pessi committed
129 130 131
/* AI extension flags - these must not overlap with existing AI flags. */

/** Message is to be sent/received compressed */
132 133 134 135
#define TP_AI_COMPRESSED 0x01000
/** Message is to be sent/received on secure connection */
#define TP_AI_SECURE     0x02000

Pekka Pessi's avatar
Pekka Pessi committed
136
/** Halfclose (shutdown(c, 1)) connection after sending message */
137
#define TP_AI_SHUTDOWN   0x04000
Pekka Pessi's avatar
Pekka Pessi committed
138
/** Close connection (shutdown(c, 2)) after sending message */
139
#define TP_AI_CLOSE      0x08000
Pekka Pessi's avatar
Pekka Pessi committed
140 141

/** Address was inaddr_any */
142
#define TP_AI_ANY        0x80000
Pekka Pessi's avatar
Pekka Pessi committed
143

144
#define TP_AI_MASK       0xff000
Pekka Pessi's avatar
Pekka Pessi committed
145

Pekka Pessi's avatar
Pekka Pessi committed
146 147 148 149 150
/** Maximum size of a @e host:port string, including final NUL. */
#define TPORT_HOSTPORTSIZE (55)

/** Transport name.
 *
151
 * This structure represents the address of the transport in textual format.
Pekka Pessi's avatar
Pekka Pessi committed
152 153 154 155 156 157 158 159 160 161 162 163 164
 * For primary transports, the transport name contains the local address,
 * for secondary transports, the peer address.
 *
 * The tpn_ident specifies the transport identifier used to make difference
 * between connectivity domains.
 */
typedef struct {
  char const *tpn_proto;	/**< Protocol name ("udp", "tcp", etc.) */
  char const *tpn_canon;	/**< Node DNS name (if known). */
  char const *tpn_host;		/**< Node address in textual format */
  char const *tpn_port;		/**< Port number in textual format. */
  char const *tpn_comp;		/**< Compression algorithm (NULL if none) */
  char const *tpn_ident;	/**< Transport identifier (NULL if none) */
165
} tp_name_t;
Pekka Pessi's avatar
Pekka Pessi committed
166 167 168 169 170 171 172 173

#define TPN_FORMAT "%s/%s:%s%s%s%s%s"

#define TPN_ARGS(n)							\
  (n)->tpn_proto, (n)->tpn_host, (n)->tpn_port,				\
  (n)->tpn_comp ? ";comp=" : "", (n)->tpn_comp ? (n)->tpn_comp : "",    \
  (n)->tpn_ident ? "/" : "", (n)->tpn_ident ? (n)->tpn_ident : ""

174
/**Create master transport. */
175
TPORT_DLL tport_t *tport_tcreate(tp_stack_t *stack,
176 177 178
				 tport_stack_class_t const *tpac,
				 su_root_t *root,
				 tag_type_t tag, tag_value_t value, ...);
Pekka Pessi's avatar
Pekka Pessi committed
179 180

/** Bind transports to network. */
181
TPORT_DLL int tport_tbind(tport_t *self,
182 183 184
			  tp_name_t const *tpn,
			  char const * const transports[],
			  tag_type_t tag, tag_value_t value, ...);
Pekka Pessi's avatar
Pekka Pessi committed
185 186

/** Get transport parameters. */
187
TPORT_DLL int tport_get_params(tport_t const *, tag_type_t tag, tag_value_t value, ...);
Pekka Pessi's avatar
Pekka Pessi committed
188 189

/** Set transport parameters. */
190
TPORT_DLL int tport_set_params(tport_t *self, tag_type_t tag, tag_value_t value, ...);
Pekka Pessi's avatar
Pekka Pessi committed
191

192
/** Destroy a master transport. */
193
TPORT_DLL void tport_destroy(tport_t *tport);
Pekka Pessi's avatar
Pekka Pessi committed
194 195

/** Shutdown a transport connection. */
196
TPORT_DLL int tport_shutdown(tport_t *tport, int how);
Pekka Pessi's avatar
Pekka Pessi committed
197

198 199 200 201 202 203 204
/** Create a new reference to a transport object. */
TPORT_DLL tport_t *tport_ref(tport_t *tp);

/** Destroy reference to a transport object. */
TPORT_DLL void tport_unref(tport_t *tp);

/** Create a new transport reference. @deprecated Use tport_ref(). */
205
TPORT_DLL tport_t *tport_incref(tport_t *tp);
Pekka Pessi's avatar
Pekka Pessi committed
206

207
/** Destroy a transport reference. @deprecated Use tport_unref(). */
208
TPORT_DLL void tport_decref(tport_t **tp);
Pekka Pessi's avatar
Pekka Pessi committed
209 210

/** Send a message using transport. */
211
TPORT_DLL tport_t *tport_tsend(tport_t *, msg_t *, tp_name_t const *,
212
			       tag_type_t, tag_value_t, ...);
Pekka Pessi's avatar
Pekka Pessi committed
213 214

/** Queue a message to transport. */
215
TPORT_DLL int tport_tqueue(tport_t *, msg_t *, tag_type_t, tag_value_t, ...);
Pekka Pessi's avatar
Pekka Pessi committed
216 217

/** Return number of queued messages. */
218
TPORT_DLL isize_t tport_queuelen(tport_t const *self);
Pekka Pessi's avatar
Pekka Pessi committed
219 220

/** Send a queued message (and queue another, if required). */
221
TPORT_DLL int tport_tqsend(tport_t *, msg_t *, msg_t *,
222
			   tag_type_t, tag_value_t, ...);
Pekka Pessi's avatar
Pekka Pessi committed
223 224

/** Stop reading from socket until tport_continue() is called. */
225
TPORT_DLL int tport_stall(tport_t *self);
Pekka Pessi's avatar
Pekka Pessi committed
226 227

/** Continue reading from socket. */
228
TPORT_DLL int tport_continue(tport_t *self);
Pekka Pessi's avatar
Pekka Pessi committed
229 230

/** Mark message as waiting for a response. */
231
TPORT_DLL int tport_pend(tport_t *self, msg_t *msg,
232
			 tport_pending_error_f *callback, tp_client_t *client);
Pekka Pessi's avatar
Pekka Pessi committed
233 234

/** Do not wait for response anymore. */
235
TPORT_DLL int tport_release(tport_t *self, int pendd,
236 237
			    msg_t *msg, msg_t *reply, tp_client_t *client,
			    int still_pending);
Pekka Pessi's avatar
Pekka Pessi committed
238 239

/** Return true if transport is master. */
Pekka Pessi's avatar
Pekka Pessi committed
240
TPORT_DLL int tport_is_master(tport_t const *self);
Pekka Pessi's avatar
Pekka Pessi committed
241 242

/** Return true if transport is primary. */
Pekka Pessi's avatar
Pekka Pessi committed
243
TPORT_DLL int tport_is_primary(tport_t const *self);
Pekka Pessi's avatar
Pekka Pessi committed
244

245 246 247
/** Return nonzero if transport is public. */
TPORT_DLL int tport_is_public(tport_t const *self);

Pekka Pessi's avatar
Pekka Pessi committed
248
/** Return true if transport is secondary. */
Pekka Pessi's avatar
Pekka Pessi committed
249
TPORT_DLL int tport_is_secondary(tport_t const *self);
Pekka Pessi's avatar
Pekka Pessi committed
250 251

/** Return true if transport is reliable, false otherwise */
Pekka Pessi's avatar
Pekka Pessi committed
252
TPORT_DLL int tport_is_reliable(tport_t const *tport);
Pekka Pessi's avatar
Pekka Pessi committed
253 254

/** Return true if transport is a stream (no message boundaries). */
Pekka Pessi's avatar
Pekka Pessi committed
255
TPORT_DLL int tport_is_stream(tport_t const *tport);
Pekka Pessi's avatar
Pekka Pessi committed
256

257 258 259
/** Return true if transport is dgram-based. */
TPORT_DLL int tport_is_dgram(tport_t const *tport);

Pekka Pessi's avatar
Pekka Pessi committed
260
/** Return true if transport supports IPv4 */
Pekka Pessi's avatar
Pekka Pessi committed
261
TPORT_DLL int tport_has_ip4(tport_t const *tport);
Pekka Pessi's avatar
Pekka Pessi committed
262 263

/** Return true if transport supports IPv6 */
Pekka Pessi's avatar
Pekka Pessi committed
264
TPORT_DLL int tport_has_ip6(tport_t const *tport);
Pekka Pessi's avatar
Pekka Pessi committed
265 266

/** Test if transport is udp. */
Pekka Pessi's avatar
Pekka Pessi committed
267
TPORT_DLL int tport_is_udp(tport_t const *self);
268

Pekka Pessi's avatar
Pekka Pessi committed
269
/** Test if transport is tcp. */
Pekka Pessi's avatar
Pekka Pessi committed
270
TPORT_DLL int tport_is_tcp(tport_t const *self);
Pekka Pessi's avatar
Pekka Pessi committed
271 272

/** Test if transport has TLS. */
Pekka Pessi's avatar
Pekka Pessi committed
273
TPORT_DLL int tport_has_tls(tport_t const *tport);
Pekka Pessi's avatar
Pekka Pessi committed
274

275 276 277
/** Test if transport provided a verified certificate chain (TLS only) */
TPORT_DLL int tport_is_verified(tport_t const *tport);

278 279
/** Return true if transport is being updated. */
TPORT_DLL int tport_is_updating(tport_t const *self);
280

281
/** Test if transport has been closed. @NEW_1_12_4. */
282 283
TPORT_DLL int tport_is_closed(tport_t const *self);

284
/** Test if transport has been shut down. @NEW_1_12_4. */
285 286
TPORT_DLL int tport_is_shutdown(tport_t const *self);

287
/** Test if transport is connected. @NEW_1_12_5. */
288 289
TPORT_DLL int tport_is_connected(tport_t const *self);

290
/** Test if transport can be used to send message. @NEW_1_12_7. */
291 292
TPORT_DLL int tport_is_clear_to_send(tport_t const *self);

Pekka Pessi's avatar
Pekka Pessi committed
293
/** Set transport magic. */
294
TPORT_DLL void tport_set_magic(tport_t *self, tp_magic_t *magic);
Pekka Pessi's avatar
Pekka Pessi committed
295 296

/** Get transport magic. */
297
TPORT_DLL tp_magic_t *tport_magic(tport_t const *tport);
Pekka Pessi's avatar
Pekka Pessi committed
298 299

/** Get transport name. */
300 301 302 303
TPORT_DLL tp_name_t const *tport_name(tport_t const *tport);

/** Get transport address list. */
TPORT_DLL su_addrinfo_t const *tport_get_address(tport_t const *tport);
Pekka Pessi's avatar
Pekka Pessi committed
304 305

/** Get transport ident. */
306
TPORT_DLL char const *tport_ident(tport_t const *self);
Pekka Pessi's avatar
Pekka Pessi committed
307 308

/** Get primary transport (or self, if already parent) */
309
TPORT_DLL tport_t *tport_parent(tport_t const *self);
Pekka Pessi's avatar
Pekka Pessi committed
310 311

/** Flush idle connections */
312
TPORT_DLL int tport_flush(tport_t *);
Pekka Pessi's avatar
Pekka Pessi committed
313 314

/** Get primary transports */
315
TPORT_DLL tport_t *tport_primaries(tport_t const *tport);
Pekka Pessi's avatar
Pekka Pessi committed
316 317

/** Get next transport */
318
TPORT_DLL tport_t *tport_next(tport_t const *tport);
Pekka Pessi's avatar
Pekka Pessi committed
319 320

/** Get secondary transports. */
321
TPORT_DLL tport_t *tport_secondary(tport_t const *tport);
Pekka Pessi's avatar
Pekka Pessi committed
322 323

/** Get a protocol corresponding to the protocol name. */
324
TPORT_DLL tport_t *tport_by_protocol(tport_t const *self, char const *proto);
Pekka Pessi's avatar
Pekka Pessi committed
325 326

/** Get transport by interface identifier and protocol name. */
327
TPORT_DLL tport_t *tport_primary_by_name(tport_t const *self, tp_name_t const *tpn);
Pekka Pessi's avatar
Pekka Pessi committed
328 329

/** Get a transport corresponding to the name */
330
TPORT_DLL tport_t *tport_by_name(tport_t const *self, tp_name_t const  *);
Pekka Pessi's avatar
Pekka Pessi committed
331 332

/** Create a transport name corresponding to the URL. */
333 334
TPORT_DLL int tport_name_by_url(su_home_t *, tp_name_t *,
				url_string_t const *us);
Pekka Pessi's avatar
Pekka Pessi committed
335 336

/** Return source transport object for delivered message */
337
TPORT_DLL tport_t *tport_delivered_by(tport_t const *tp, msg_t const *msg);
Pekka Pessi's avatar
Pekka Pessi committed
338 339

/** Return source transport name for delivered message */
340 341
TPORT_DLL int tport_delivered_from(tport_t *tp, msg_t const *msg,
				   tp_name_t name[1]);
Pekka Pessi's avatar
Pekka Pessi committed
342

343
/** Return TLS Subjects provided by the source transport */
344
TPORT_DLL su_strlst_t const *tport_delivered_from_subjects(tport_t *tp,
345
                                                           msg_t const *msg);
346 347 348
/** Return TLS client certificate sha1 fingerprint (20 packets of 2 hexa digits)*/
TPORT_DLL unsigned char *tport_delivered_sha1_fingerprint(tport_t *tp,
                                                           msg_t const *msg);
349 350
/** Check if the given subject string is found in su_strlst_t */
TPORT_DLL int tport_subject_search(char const *, su_strlst_t const *);
351

Pekka Pessi's avatar
Pekka Pessi committed
352
/** Check if transport named is already resolved */
353
TPORT_DLL int tport_name_is_resolved(tp_name_t const *);
Pekka Pessi's avatar
Pekka Pessi committed
354 355

/** Duplicate a transport name. */
356 357
TPORT_DLL int tport_name_dup(su_home_t *,
			     tp_name_t *dst, tp_name_t const *src);
Pekka Pessi's avatar
Pekka Pessi committed
358 359

/** Convert a socket address to a transport name. */
360
TPORT_DLL int tport_convert_addr(su_home_t *home,
361 362 363 364
				 tp_name_t *tpn,
				 char const *protoname,
				 char const *canon,
				 su_sockaddr_t const *su);
Pekka Pessi's avatar
Pekka Pessi committed
365 366

/** Print host and port separated with ':' to a string. */
367
TPORT_DLL char *tport_hostport(char buf[], isize_t bufsize,
368
			       su_sockaddr_t const *su, int with_port);
Pekka Pessi's avatar
Pekka Pessi committed
369

370
/** Initialize STUN keepalives. */
371 372
TPORT_DLL int tport_keepalive(tport_t *tp, su_addrinfo_t const *ai,
			      tag_type_t tag, tag_value_t value, ...);
373

374
TPORT_DLL float tport_get_packet_count_rate(tport_t *tp);
375
TPORT_DLL void tport_reset_packet_count_rate(tport_t *tp);
376

Pekka Pessi's avatar
Pekka Pessi committed
377 378 379
/* ---------------------------------------------------------------------- */
/* SigComp-related functions */

380 381 382 383 384
#ifndef TPORT_COMPRESSOR
#define TPORT_COMPRESSOR struct tport_compressor
#endif

typedef TPORT_COMPRESSOR tport_compressor_t;
385

386 387
TPORT_DLL int tport_can_send_sigcomp(tport_t const *self);
TPORT_DLL int tport_can_recv_sigcomp(tport_t const *self);
Pekka Pessi's avatar
Pekka Pessi committed
388

389 390
TPORT_DLL int tport_has_compression(tport_t const *self, char const *comp);
TPORT_DLL int tport_set_compression(tport_t *self, char const *comp);
Pekka Pessi's avatar
Pekka Pessi committed
391 392

/** Set SigComp option. */
393 394
TPORT_DLL
int tport_sigcomp_option(tport_t const *self,
395
			 struct sigcomp_compartment *cc,
Pekka Pessi's avatar
Pekka Pessi committed
396 397 398
			 char const *option);

/** Obtain a SigComp compartment with given name. */
399 400
TPORT_DLL struct sigcomp_compartment *
tport_sigcomp_compartment(tport_t *self,
401
			  char const *name, isize_t namelen,
Pekka Pessi's avatar
Pekka Pessi committed
402 403 404
			  int create_if_needed);

/** Assign a SigComp compartment to a connection-oriented tport. */
405 406
TPORT_DLL int
tport_sigcomp_assign(tport_t *self, struct sigcomp_compartment *);
Pekka Pessi's avatar
Pekka Pessi committed
407 408

/** Test if a SigComp compartment is assigned to a tport. */
409
TPORT_DLL int tport_has_sigcomp_assigned(tport_t const *self);
Pekka Pessi's avatar
Pekka Pessi committed
410 411

/** Accept SigComp message */
412 413 414 415
TPORT_DLL int
tport_sigcomp_accept(tport_t *self,
		     struct sigcomp_compartment *cc,
		     msg_t *msg);
Pekka Pessi's avatar
Pekka Pessi committed
416

417
/** Get compressor context with which the request was delivered */
418
TPORT_DLL int
419 420
tport_delivered_with_comp(tport_t *tp, msg_t const *msg,
			  tport_compressor_t **return_compressor);
Pekka Pessi's avatar
Pekka Pessi committed
421 422

/** Shutdown SigComp compartment */
423 424 425 426
TPORT_DLL int
tport_sigcomp_close(tport_t *self,
		    struct sigcomp_compartment *cc,
		    int how);
Pekka Pessi's avatar
Pekka Pessi committed
427 428

/** Set SigComp compartment lifetime. */
429 430 431 432 433
TPORT_DLL int
tport_sigcomp_lifetime(tport_t *self,
		       struct sigcomp_compartment *,
		       unsigned lifetime_in_ms,
		       int only_expand);
Pekka Pessi's avatar
Pekka Pessi committed
434 435


436 437
SOFIA_END_DECLS

Pekka Pessi's avatar
Pekka Pessi committed
438
#endif /* TPORT_H */