tport.h 12.6 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 25
 * 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
 *
 */

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

#ifndef SU_H
36
#include <sofia-sip/su.h>
Pekka Pessi's avatar
Pekka Pessi committed
37 38
#endif
#ifndef SU_WAIT_H
39
#include <sofia-sip/su_wait.h>
Pekka Pessi's avatar
Pekka Pessi committed
40 41
#endif
#ifndef MSG_H
42
#include <sofia-sip/msg.h>
Pekka Pessi's avatar
Pekka Pessi committed
43 44
#endif
#ifndef URL_H
45
#include <sofia-sip/url.h>
Pekka Pessi's avatar
Pekka Pessi committed
46 47
#endif

48 49
SOFIA_BEGIN_DECLS

50 51 52 53 54
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
55 56 57 58 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

#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 */
90
  void   (*tpac_recv)(tp_stack_t *, tport_t *, msg_t *msg, tp_magic_t *magic,
Pekka Pessi's avatar
Pekka Pessi committed
91 92 93
		      su_time_t received);

  /** Function used to indicate an error to the protocol stack */
94
  void   (*tpac_error)(tp_stack_t *, tport_t *,
Pekka Pessi's avatar
Pekka Pessi committed
95 96 97
		       int errcode, char const *remote);

  /** Ask stack to allocate a message. */
98
  msg_t *(*tpac_alloc)(tp_stack_t *, int flags,
Pekka Pessi's avatar
Pekka Pessi committed
99 100 101
		       char const [], unsigned,
		       tport_t const *, tp_client_t *);

102 103 104
  /** Indicate stack that address has changed */
  void (*tpac_address)(tp_stack_t *, tport_t *);

105
} tport_stack_class_t;
Pekka Pessi's avatar
Pekka Pessi committed
106 107

/* Compatibility */
108
typedef tport_stack_class_t tp_stack_class_t;
Pekka Pessi's avatar
Pekka Pessi committed
109 110

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

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

119

Pekka Pessi's avatar
Pekka Pessi committed
120 121 122
/* AI extension flags - these must not overlap with existing AI flags. */

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

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

135
#define TP_AI_MASK       0xff000
Pekka Pessi's avatar
Pekka Pessi committed
136

Pekka Pessi's avatar
Pekka Pessi committed
137 138 139 140 141
/** Maximum size of a @e host:port string, including final NUL. */
#define TPORT_HOSTPORTSIZE (55)

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

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

165
#include <sofia-sip/tport_tag.h>
Pekka Pessi's avatar
Pekka Pessi committed
166 167

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

/** Duplicate a transport name. */
325
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
326 327

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

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

Martti Mela's avatar
Martti Mela committed
338
/** Initialize STUN keepalives. */
339 340
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
341

Pekka Pessi's avatar
Pekka Pessi committed
342 343 344
/* ---------------------------------------------------------------------- */
/* SigComp-related functions */

345 346 347 348 349
#ifndef TPORT_COMPRESSOR
#define TPORT_COMPRESSOR struct tport_compressor
#endif

typedef TPORT_COMPRESSOR tport_compressor_t;
350

351 352
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
353

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

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

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

369
TPORT_DLL struct sigcomp_compartment *
Pekka Pessi's avatar
Pekka Pessi committed
370 371
tport_compartment_incref(struct sigcomp_compartment *cc);

372
TPORT_DLL void
Pekka Pessi's avatar
Pekka Pessi committed
373 374 375
tport_compartment_decref(struct sigcomp_compartment **pointer_to_cc);

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

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

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

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

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

/** Set SigComp compartment lifetime. */
400 401 402 403 404
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
405 406


407 408
SOFIA_END_DECLS

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