tport.h 12.9 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 isize_t 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

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

273 274 275 276 277 278
/** Test if transport has been closed (added to @VERSION_1_12_4 ) */
TPORT_DLL int tport_is_closed(tport_t const *self);

/** Test if transport has been shut down (added to @VERSION_1_12_4 ) */
TPORT_DLL int tport_is_shutdown(tport_t const *self);

Pekka Pessi's avatar
Pekka Pessi committed
279
/** Set transport magic. */
280
TPORT_DLL void tport_set_magic(tport_t *self, tp_magic_t *magic);
Pekka Pessi's avatar
Pekka Pessi committed
281 282

/** Get transport magic. */
283
TPORT_DLL tp_magic_t *tport_magic(tport_t const *tport);
Pekka Pessi's avatar
Pekka Pessi committed
284 285

/** Get transport name. */
286 287 288 289
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
290 291

/** Get transport ident. */
292
TPORT_DLL char const *tport_ident(tport_t const *self);
Pekka Pessi's avatar
Pekka Pessi committed
293 294

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

/** Flush idle connections */
298
TPORT_DLL int tport_flush(tport_t *);
Pekka Pessi's avatar
Pekka Pessi committed
299 300

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

/** Get next transport */
304
TPORT_DLL tport_t *tport_next(tport_t const *tport);
Pekka Pessi's avatar
Pekka Pessi committed
305 306

/** Get secondary transports. */
307
TPORT_DLL tport_t *tport_secondary(tport_t const *tport);
Pekka Pessi's avatar
Pekka Pessi committed
308 309

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

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

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

/** Create a transport name corresponding to the URL. */
319 320
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
321 322

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

/** Return source transport name for delivered message */
326 327
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
328 329

/** Check if transport named is already resolved */
330
TPORT_DLL int tport_name_is_resolved(tp_name_t const *);
Pekka Pessi's avatar
Pekka Pessi committed
331 332

/** Duplicate a transport name. */
333 334
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
335 336

/** Convert a socket address to a transport name. */
337
TPORT_DLL int tport_convert_addr(su_home_t *home,
338 339 340 341
				 tp_name_t *tpn,
				 char const *protoname,
				 char const *canon,
				 su_sockaddr_t const *su);
Pekka Pessi's avatar
Pekka Pessi committed
342 343

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

347
/** Initialize STUN keepalives. */
348 349
TPORT_DLL int tport_keepalive(tport_t *tp, su_addrinfo_t const *ai,
			      tag_type_t tag, tag_value_t value, ...);
350

Pekka Pessi's avatar
Pekka Pessi committed
351 352 353
/* ---------------------------------------------------------------------- */
/* SigComp-related functions */

354 355 356 357 358
#ifndef TPORT_COMPRESSOR
#define TPORT_COMPRESSOR struct tport_compressor
#endif

typedef TPORT_COMPRESSOR tport_compressor_t;
359

360 361
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
362

363 364
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
365 366

/** Set SigComp option. */
367 368
TPORT_DLL
int tport_sigcomp_option(tport_t const *self,
369
			 struct sigcomp_compartment *cc,
Pekka Pessi's avatar
Pekka Pessi committed
370 371 372
			 char const *option);

/** Obtain a SigComp compartment with given name. */
373 374
TPORT_DLL struct sigcomp_compartment *
tport_sigcomp_compartment(tport_t *self,
375
			  char const *name, isize_t namelen,
Pekka Pessi's avatar
Pekka Pessi committed
376 377
			  int create_if_needed);

378
TPORT_DLL struct sigcomp_compartment *
Pekka Pessi's avatar
Pekka Pessi committed
379 380
tport_compartment_incref(struct sigcomp_compartment *cc);

381
TPORT_DLL void
Pekka Pessi's avatar
Pekka Pessi committed
382 383 384
tport_compartment_decref(struct sigcomp_compartment **pointer_to_cc);

/** Assign a SigComp compartment to a connection-oriented tport. */
385 386
TPORT_DLL int
tport_sigcomp_assign(tport_t *self, struct sigcomp_compartment *);
Pekka Pessi's avatar
Pekka Pessi committed
387 388

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

/** Accept SigComp message */
392 393 394 395
TPORT_DLL int
tport_sigcomp_accept(tport_t *self,
		     struct sigcomp_compartment *cc,
		     msg_t *msg);
Pekka Pessi's avatar
Pekka Pessi committed
396

397
/** Get compressor context with which the request was delivered */
398
TPORT_DLL int
399 400
tport_delivered_with_comp(tport_t *tp, msg_t const *msg,
			  tport_compressor_t **return_compressor);
Pekka Pessi's avatar
Pekka Pessi committed
401 402

/** Shutdown SigComp compartment */
403 404 405 406
TPORT_DLL int
tport_sigcomp_close(tport_t *self,
		    struct sigcomp_compartment *cc,
		    int how);
Pekka Pessi's avatar
Pekka Pessi committed
407 408

/** Set SigComp compartment lifetime. */
409 410 411 412 413
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
414 415


416 417
SOFIA_END_DECLS

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