tport.h 13.3 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
SOFIA_BEGIN_DECLS

57 58 59 60 61
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
62 63 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

#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 */
97
  void   (*tpac_recv)(tp_stack_t *, tport_t *, msg_t *msg, tp_magic_t *magic,
Pekka Pessi's avatar
Pekka Pessi committed
98 99 100
		      su_time_t received);

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

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

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

112
} tport_stack_class_t;
Pekka Pessi's avatar
Pekka Pessi committed
113 114

/* Compatibility */
115
typedef tport_stack_class_t tp_stack_class_t;
Pekka Pessi's avatar
Pekka Pessi committed
116 117

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

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

126

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

/** Message is to be sent/received compressed */
130 131 132 133
#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
134
/** Halfclose (shutdown(c, 1)) connection after sending message */
135
#define TP_AI_SHUTDOWN   0x04000
Pekka Pessi's avatar
Pekka Pessi committed
136
/** Close connection (shutdown(c, 2)) after sending message */
137
#define TP_AI_CLOSE      0x08000
Pekka Pessi's avatar
Pekka Pessi committed
138 139

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

142
#define TP_AI_MASK       0xff000
Pekka Pessi's avatar
Pekka Pessi committed
143

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

/** Transport name.
 *
149
 * This structure represents the address of the transport in textual format.
Pekka Pessi's avatar
Pekka Pessi committed
150 151 152 153 154 155 156 157 158 159 160 161 162
 * 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) */
163
} tp_name_t;
Pekka Pessi's avatar
Pekka Pessi committed
164 165 166 167 168 169 170 171

#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 : ""

172
/**Create master transport. */
173
TPORT_DLL tport_t *tport_tcreate(tp_stack_t *stack,
174 175 176
				 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
177 178

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

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

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

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

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

196 197 198 199 200 201 202
/** 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(). */
203
TPORT_DLL tport_t *tport_incref(tport_t *tp);
Pekka Pessi's avatar
Pekka Pessi committed
204

205
/** Destroy a transport reference. @deprecated Use tport_unref(). */
206
TPORT_DLL void tport_decref(tport_t **tp);
Pekka Pessi's avatar
Pekka Pessi committed
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, ...);
Pekka Pessi's avatar
Pekka Pessi committed
211 212

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

/** Return number of queued messages. */
216
TPORT_DLL isize_t tport_queuelen(tport_t const *self);
Pekka Pessi's avatar
Pekka Pessi committed
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, ...);
Pekka Pessi's avatar
Pekka Pessi committed
221 222

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

/** Continue reading from socket. */
226
TPORT_DLL int tport_continue(tport_t *self);
Pekka Pessi's avatar
Pekka Pessi committed
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);
Pekka Pessi's avatar
Pekka Pessi committed
231 232

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

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

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

Pekka Pessi's avatar
Pekka Pessi committed
243 244 245
/** Return nonzero if transport is public. */
TPORT_DLL int tport_is_public(tport_t const *self);

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

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

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

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

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

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

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

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

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

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

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

Pekka Pessi's avatar
Pekka Pessi committed
279
/** Test if transport has been closed. @NEW_1_12_4. */
280 281
TPORT_DLL int tport_is_closed(tport_t const *self);

Pekka Pessi's avatar
Pekka Pessi committed
282
/** Test if transport has been shut down. @NEW_1_12_4. */
283 284
TPORT_DLL int tport_is_shutdown(tport_t const *self);

Pekka Pessi's avatar
Pekka Pessi committed
285
/** Test if transport is connected. @NEW_1_12_5. */
286 287
TPORT_DLL int tport_is_connected(tport_t const *self);

Pekka Pessi's avatar
Pekka Pessi committed
288
/** Test if transport can be used to send message. @NEW_1_12_7. */
289 290
TPORT_DLL int tport_is_clear_to_send(tport_t const *self);

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

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

/** Get transport name. */
298 299 300 301
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
302 303

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

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

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

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

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

/** Get secondary transports. */
319
TPORT_DLL tport_t *tport_secondary(tport_t const *tport);
Pekka Pessi's avatar
Pekka Pessi committed
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);
Pekka Pessi's avatar
Pekka Pessi committed
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);
Pekka Pessi's avatar
Pekka Pessi committed
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  *);
Pekka Pessi's avatar
Pekka Pessi committed
329 330

/** Create a transport name corresponding to the URL. */
331 332
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
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);
Pekka Pessi's avatar
Pekka Pessi committed
336 337

/** Return source transport name for delivered message */
338 339
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
340

341 342 343
/** Return TLS Subjects provided by the source transport */
TPORT_DLL su_strlst_t *tport_delivered_from_subjects(tport_t *tp, msg_t const *msg);

Pekka Pessi's avatar
Pekka Pessi committed
344
/** Check if transport named is already resolved */
345
TPORT_DLL int tport_name_is_resolved(tp_name_t const *);
Pekka Pessi's avatar
Pekka Pessi committed
346 347

/** Duplicate a transport name. */
348 349
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
350 351

/** Convert a socket address to a transport name. */
352
TPORT_DLL int tport_convert_addr(su_home_t *home,
353 354 355 356
				 tp_name_t *tpn,
				 char const *protoname,
				 char const *canon,
				 su_sockaddr_t const *su);
Pekka Pessi's avatar
Pekka Pessi committed
357 358

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

Martti Mela's avatar
Martti Mela committed
362
/** Initialize STUN keepalives. */
363 364
TPORT_DLL int tport_keepalive(tport_t *tp, su_addrinfo_t const *ai,
			      tag_type_t tag, tag_value_t value, ...);
Martti Mela's avatar
Martti Mela committed
365

Pekka Pessi's avatar
Pekka Pessi committed
366 367 368
/* ---------------------------------------------------------------------- */
/* SigComp-related functions */

369 370 371 372 373
#ifndef TPORT_COMPRESSOR
#define TPORT_COMPRESSOR struct tport_compressor
#endif

typedef TPORT_COMPRESSOR tport_compressor_t;
374

375 376
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
377

378 379
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
380 381

/** Set SigComp option. */
382 383
TPORT_DLL
int tport_sigcomp_option(tport_t const *self,
384
			 struct sigcomp_compartment *cc,
Pekka Pessi's avatar
Pekka Pessi committed
385 386 387
			 char const *option);

/** Obtain a SigComp compartment with given name. */
388 389
TPORT_DLL struct sigcomp_compartment *
tport_sigcomp_compartment(tport_t *self,
390
			  char const *name, isize_t namelen,
Pekka Pessi's avatar
Pekka Pessi committed
391 392 393
			  int create_if_needed);

/** Assign a SigComp compartment to a connection-oriented tport. */
394 395
TPORT_DLL int
tport_sigcomp_assign(tport_t *self, struct sigcomp_compartment *);
Pekka Pessi's avatar
Pekka Pessi committed
396 397

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

/** Accept SigComp message */
401 402 403 404
TPORT_DLL int
tport_sigcomp_accept(tport_t *self,
		     struct sigcomp_compartment *cc,
		     msg_t *msg);
Pekka Pessi's avatar
Pekka Pessi committed
405

406
/** Get compressor context with which the request was delivered */
407
TPORT_DLL int
408 409
tport_delivered_with_comp(tport_t *tp, msg_t const *msg,
			  tport_compressor_t **return_compressor);
Pekka Pessi's avatar
Pekka Pessi committed
410 411

/** Shutdown SigComp compartment */
412 413 414 415
TPORT_DLL int
tport_sigcomp_close(tport_t *self,
		    struct sigcomp_compartment *cc,
		    int how);
Pekka Pessi's avatar
Pekka Pessi committed
416 417

/** Set SigComp compartment lifetime. */
418 419 420 421 422
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
423 424


425 426
SOFIA_END_DECLS

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