tport.h 12.7 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 39
#endif
#ifndef SU_WAIT_H
40
#include <sofia-sip/su_wait.h>
Pekka Pessi's avatar
Pekka Pessi committed
41 42
#endif
#ifndef MSG_H
43
#include <sofia-sip/msg.h>
Pekka Pessi's avatar
Pekka Pessi committed
44 45
#endif
#ifndef URL_H
46
#include <sofia-sip/url.h>
Pekka Pessi's avatar
Pekka Pessi committed
47
#endif
48 49 50
#ifndef TPORT_TAG_H
#include <sofia-sip/tport_tag.h>
#endif
Pekka Pessi's avatar
Pekka Pessi committed
51

52 53
SOFIA_BEGIN_DECLS

54 55 56 57 58
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
59 60 61 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

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

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

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

106 107 108
  /** Indicate stack that address has changed */
  void (*tpac_address)(tp_stack_t *, tport_t *);

109
} tport_stack_class_t;
Pekka Pessi's avatar
Pekka Pessi committed
110 111

/* Compatibility */
112
typedef tport_stack_class_t tp_stack_class_t;
Pekka Pessi's avatar
Pekka Pessi committed
113 114

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

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

123

Pekka Pessi's avatar
Pekka Pessi committed
124 125 126
/* AI extension flags - these must not overlap with existing AI flags. */

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

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

139
#define TP_AI_MASK       0xff000
Pekka Pessi's avatar
Pekka Pessi committed
140

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

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

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

/** Create first primary transport. */
170
TPORT_DLL tport_t *tport_tcreate(tp_stack_t *stack,
171 172 173
				 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
174 175

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

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

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

/** Destroy transport(s). */
188
TPORT_DLL void tport_destroy(tport_t *tport);
Pekka Pessi's avatar
Pekka Pessi committed
189 190

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

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

202
/** Destroy a transport reference. @deprecated Use tport_unref(). */
203
TPORT_DLL void tport_decref(tport_t **tp);
Pekka Pessi's avatar
Pekka Pessi committed
204 205

/** Send a message using transport. */
206
TPORT_DLL tport_t *tport_tsend(tport_t *, msg_t *, tp_name_t const *,
207
			       tag_type_t, tag_value_t, ...);
Pekka Pessi's avatar
Pekka Pessi committed
208 209

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

/** Return number of queued messages. */
213
TPORT_DLL int tport_queuelen(tport_t const *self);
Pekka Pessi's avatar
Pekka Pessi committed
214 215

/** Send a queued message (and queue another, if required). */
216 217
TPORT_DLL int tport_tqsend(tport_t *, msg_t *, msg_t *, 
			   tag_type_t, tag_value_t, ...);
Pekka Pessi's avatar
Pekka Pessi committed
218 219

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

/** Continue reading from socket. */
223
TPORT_DLL int tport_continue(tport_t *self);
Pekka Pessi's avatar
Pekka Pessi committed
224 225

/** Mark message as waiting for a response. */
226
TPORT_DLL int tport_pend(tport_t *self, msg_t *msg,
227
			 tport_pending_error_f *callback, tp_client_t *client);
Pekka Pessi's avatar
Pekka Pessi committed
228 229

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

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

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

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

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

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

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

252 253 254
/** Return true if transport is dgram-based. */
TPORT_DLL int tport_is_dgram(tport_t const *tport);

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

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

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

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

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

270 271
/** Return true if transport is being updated. */
TPORT_DLL int tport_is_updating(tport_t const *self);
272

Pekka Pessi's avatar
Pekka Pessi committed
273
/** Set transport magic. */
274
TPORT_DLL void tport_set_magic(tport_t *self, tp_magic_t *magic);
Pekka Pessi's avatar
Pekka Pessi committed
275 276

/** Get transport magic. */
277
TPORT_DLL tp_magic_t *tport_magic(tport_t const *tport);
Pekka Pessi's avatar
Pekka Pessi committed
278 279

/** Get transport name. */
280 281 282 283
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
284 285

/** Get transport ident. */
286
TPORT_DLL char const *tport_ident(tport_t const *self);
Pekka Pessi's avatar
Pekka Pessi committed
287 288

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

/** Flush idle connections */
292
TPORT_DLL int tport_flush(tport_t *);
Pekka Pessi's avatar
Pekka Pessi committed
293 294

/** Get primary transports */
295
TPORT_DLL tport_t *tport_primaries(tport_t const *tport);
Pekka Pessi's avatar
Pekka Pessi committed
296 297

/** Get next transport */
298
TPORT_DLL tport_t *tport_next(tport_t const *tport);
Pekka Pessi's avatar
Pekka Pessi committed
299 300

/** Get secondary transports. */
301
TPORT_DLL tport_t *tport_secondary(tport_t const *tport);
Pekka Pessi's avatar
Pekka Pessi committed
302 303

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

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

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

/** Create a transport name corresponding to the URL. */
313 314
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
315 316

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

/** Return source transport name for delivered message */
320 321
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
322 323

/** Check if transport named is already resolved */
324
TPORT_DLL int tport_name_is_resolved(tp_name_t const *);
Pekka Pessi's avatar
Pekka Pessi committed
325 326

/** Duplicate a transport name. */
327 328
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
329 330

/** Convert a socket address to a transport name. */
331
TPORT_DLL int tport_convert_addr(su_home_t *home,
332 333 334 335
				 tp_name_t *tpn,
				 char const *protoname,
				 char const *canon,
				 su_sockaddr_t const *su);
Pekka Pessi's avatar
Pekka Pessi committed
336 337

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

Martti Mela's avatar
Martti Mela committed
341
/** Initialize STUN keepalives. */
342 343
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
344

Pekka Pessi's avatar
Pekka Pessi committed
345 346 347
/* ---------------------------------------------------------------------- */
/* SigComp-related functions */

348 349 350 351 352
#ifndef TPORT_COMPRESSOR
#define TPORT_COMPRESSOR struct tport_compressor
#endif

typedef TPORT_COMPRESSOR tport_compressor_t;
353

354 355
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
356

357 358
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
359 360

/** Set SigComp option. */
361 362
TPORT_DLL
int tport_sigcomp_option(tport_t const *self,
363
			 struct sigcomp_compartment *cc,
Pekka Pessi's avatar
Pekka Pessi committed
364 365 366
			 char const *option);

/** Obtain a SigComp compartment with given name. */
367 368
TPORT_DLL struct sigcomp_compartment *
tport_sigcomp_compartment(tport_t *self,
369
			  char const *name, isize_t namelen,
Pekka Pessi's avatar
Pekka Pessi committed
370 371
			  int create_if_needed);

372
TPORT_DLL struct sigcomp_compartment *
Pekka Pessi's avatar
Pekka Pessi committed
373 374
tport_compartment_incref(struct sigcomp_compartment *cc);

375
TPORT_DLL void
Pekka Pessi's avatar
Pekka Pessi committed
376 377 378
tport_compartment_decref(struct sigcomp_compartment **pointer_to_cc);

/** Assign a SigComp compartment to a connection-oriented tport. */
379 380
TPORT_DLL int
tport_sigcomp_assign(tport_t *self, struct sigcomp_compartment *);
Pekka Pessi's avatar
Pekka Pessi committed
381 382

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

/** Accept SigComp message */
386 387 388 389
TPORT_DLL int
tport_sigcomp_accept(tport_t *self,
		     struct sigcomp_compartment *cc,
		     msg_t *msg);
Pekka Pessi's avatar
Pekka Pessi committed
390

391
/** Get compressor context with which the request was delivered */
392
TPORT_DLL int
393 394
tport_delivered_with_comp(tport_t *tp, msg_t const *msg,
			  tport_compressor_t **return_compressor);
Pekka Pessi's avatar
Pekka Pessi committed
395 396

/** Shutdown SigComp compartment */
397 398 399 400
TPORT_DLL int
tport_sigcomp_close(tport_t *self,
		    struct sigcomp_compartment *cc,
		    int how);
Pekka Pessi's avatar
Pekka Pessi committed
401 402

/** Set SigComp compartment lifetime. */
403 404 405 406 407
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
408 409


410 411
SOFIA_END_DECLS

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