tport.h

Internet Phone, Chat, Conferencing

/*
 * This file is part of the Sofia-SIP package
 *
 * Copyright (C) 2005 Nokia Corporation.
 *
 * Contact: Pekka Pessi <[e-mail]>
 *
 * This library is free software; you can redistribute it and/or
 * 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. */
#define TPORT_H
/**@file tport.h
 * @brief Transport interface 
 *
 * @author Pekka Pessi <[e-mail]>
 *
 * @date Created: Thu Jun 29 15:58:06 2000 ppessi
 */

#ifndef SU_H
#include <sofia-sip/su.h>
#endif
#ifndef SU_WAIT_H
#include <sofia-sip/su_wait.h>
#endif
#ifndef MSG_H
#include <sofia-sip/msg.h>
#endif
#ifndef URL_H
#include <sofia-sip/url.h>
#endif

SOFIA_BEGIN_DECLS

struct tport_s;
#ifndef TPORT_T
#define TPORT_T struct tport_s
typedef TPORT_T tport_t;
#endif

#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 */
  void   (*tpac_recv)(tp_stack_t *, tport_t *, msg_t *msg, tp_magic_t *magic, 
		      su_time_t received);

  /** Function used to indicate an error to the protocol stack */
  void   (*tpac_error)(tp_stack_t *, tport_t *, 
		       int errcode, char const *remote);

  /** Ask stack to allocate a message. */
  msg_t *(*tpac_alloc)(tp_stack_t *, int flags, 
		       char const [], unsigned,
		       tport_t const *, tp_client_t *);

  /** Ask stack to accept/reject early SigComp message */
  int (*tpac_sigcomp_accept)(tp_stack_t *, tport_t *, msg_t *);

} tport_stack_class_t;

/* Compatibility */
typedef tport_stack_class_t tp_stack_class_t;

/** Callback to report error by pending requests. */
typedef void tport_pending_error_f(tp_stack_t *, tp_client_t *, 
				   tport_t *, msg_t *msg, int error);

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

/* AI extension flags - these must not overlap with existing AI flags. */

/** Message is to be sent/received compressed */
#define TP_AI_COMPRESSED 0x1000
/** Halfclose (shutdown(c, 1)) connection after sending message */
#define TP_AI_SHUTDOWN   0x2000
/** Close connection (shutdown(c, 2)) after sending message */
#define TP_AI_CLOSE      0x4000

/** Address was inaddr_any */
#define TP_AI_ANY        0x8000

#define TP_AI_MASK       0xf000

/** Maximum size of a @e host:port string, including final NUL. */
#define TPORT_HOSTPORTSIZE (55)

/** Transport name.
 *
 * This structure represents the address of the transport in textual format. 
 * 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) */
} tp_name_t; 

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

#include <sofia-sip/tport_tag.h>

/** Create first primary transport. */
tport_t *tport_tcreate(tp_stack_t *stack,
		       tport_stack_class_t const *tpac,
		       su_root_t *root, 
		       tag_type_t tag, tag_value_t value, ...);

/** Create first primary transport. @deprecated Use tport_tcreate(). */
tport_t *tport_create(tp_stack_t *stack,
		      tport_stack_class_t const *stack_class,
		      su_root_t *root);

/** Bind transports to network */
int tport_bind(tport_t *self,
	       tp_name_t const *tpn,
	       char const * const transports[],
	       int flags);

/** Bind transports to network. */
int tport_tbind(tport_t *self,
		tp_name_t const *tpn,
		char const * const transports[],
		tag_type_t tag, tag_value_t value, ...);

/** Get transport parameters. */
int tport_get_params(tport_t const *, tag_type_t tag, tag_value_t value, ...);

/** Set transport parameters. */
int tport_set_params(tport_t *self, tag_type_t tag, tag_value_t value, ...);

/** Destroy transport(s). */
void tport_destroy(tport_t *tport);

/** Shutdown a transport connection. */
int tport_shutdown(tport_t *tport, int how);

/** Create a new transport reference. */
tport_t *tport_incref(tport_t *tp);

/** Destroy a transport reference. */
void tport_decref(tport_t **tp);

/** Send a message using transport. @deprecated Use tport_tsend(). */
int tport_send(tport_t *, msg_t *, tp_name_t const *);

/** Send a message using transport. */
tport_t *tport_tsend(tport_t *, msg_t *, tp_name_t const *, 
		     tag_type_t, tag_value_t, ...);

/** Queue a message to transport. */
int tport_tqueue(tport_t *, msg_t *, tag_type_t, tag_value_t, ...);

/** Return number of queued messages. */
int tport_queuelen(tport_t const *self);

/** Send a queued message (and queue another, if required). */
int tport_tqsend(tport_t *, msg_t *, msg_t *, tag_type_t, tag_value_t, ...);

/** Stop reading from socket until tport_continue() is called. */
int tport_stall(tport_t *self);

/** Continue reading from socket. */
int tport_continue(tport_t *self);

/** Mark message as waiting for a response. */
int tport_pend(tport_t *self, msg_t *msg, 
	       tport_pending_error_f *callback, tp_client_t *client);

/** Do not wait for response anymore. */
int tport_release(tport_t *self, int pendd,		  
		  msg_t *msg, msg_t *reply, tp_client_t *client, 
		  int still_pending);

/** Return true if transport is master. */
TPORT_DLL int tport_is_master(tport_t const *self);

/** Return true if transport is primary. */
TPORT_DLL int tport_is_primary(tport_t const *self);

/** Return true if transport is secondary. */
TPORT_DLL int tport_is_secondary(tport_t const *self);

/** Return true if transport is reliable, false otherwise */
TPORT_DLL int tport_is_reliable(tport_t const *tport);

/** Return true if transport is a stream (no message boundaries). */
TPORT_DLL int tport_is_stream(tport_t const *tport);

/** Return true if transport supports IPv4 */
TPORT_DLL int tport_has_ip4(tport_t const *tport);

/** Return true if transport supports IPv6 */
TPORT_DLL int tport_has_ip6(tport_t const *tport);

/** Test if transport is udp. */
TPORT_DLL int tport_is_udp(tport_t const *self);
 
/** Test if transport is tcp. */
TPORT_DLL int tport_is_tcp(tport_t const *self);

/** Test if transport has TLS. */
TPORT_DLL int tport_has_tls(tport_t const *tport);

/** Test if transport has just been accepted. */
int tport_is_newly_accepted(tport_t *self);
 
/** Set transport magic. */
void tport_set_magic(tport_t *self, tp_magic_t *magic);

/** Get transport magic. */
tp_magic_t *tport_magic(tport_t const *tport);

/** Get transport name. */
tp_name_t const *tport_name(tport_t const *tport);

/** Get transport ident. */
char const *tport_ident(tport_t const *self);

/** Get primary transport (or self, if already parent) */
tport_t *tport_parent(tport_t const *self);

/** Flush idle connections */
int tport_flush(tport_t *);

/** Get primary transports */
tport_t *tport_primaries(tport_t const *tport);

/** Get next transport */
tport_t *tport_next(tport_t const *tport);

/** Get secondary transports. */
tport_t *tport_secondary(tport_t const *tport);

/** Get a protocol corresponding to the protocol name. */
tport_t *tport_by_protocol(tport_t const *self, char const *proto);

/** Get transport by interface identifier and protocol name. */
tport_t *tport_primary_by_name(tport_t const *self, tp_name_t const *tpn);

/** Get a transport corresponding to the name */
tport_t *tport_by_name(tport_t const *self, tp_name_t const  *);

/** Create a transport name corresponding to the URL. */
int tport_name_by_url(su_home_t *, tp_name_t *, url_string_t const *us);

/** Return source transport object for delivered message */
tport_t *tport_delivered_by(tport_t const *tp, msg_t const *msg);

/** Return source transport name for delivered message */
int tport_delivered_from(tport_t *tp, msg_t const *msg, tp_name_t name[1]);

/** Check if transport named is already resolved */
int tport_name_is_resolved(tp_name_t const *);

/** Duplicate a transport name. */
int tport_name_dup(su_home_t *, tp_name_t *dst, tp_name_t const *src);

/** Convert a socket address to a transport name. */
int tport_convert_addr(su_home_t *home,
		       tp_name_t *tpn,
		       char const *protoname,
		       char const *canon,
		       su_sockaddr_t const *su);

/** Print host and port separated with ':' to a string. */
char *tport_hostport(char buf[], int bufsize, 
		     su_sockaddr_t const *su, int with_port);

/** Initialize STUN keepalives. */
int tport_keepalive(tport_t *tp, tp_name_t *tpn);

/* ---------------------------------------------------------------------- */
/* SigComp-related functions */

int tport_can_send_sigcomp(tport_t const *self);
int tport_can_recv_sigcomp(tport_t const *self);

int tport_has_compression(tport_t const *self, char const *comp);
int tport_set_compression(tport_t *self, char const *comp);

/** Set SigComp option. */
int tport_sigcomp_option(tport_t const *self,
			 struct sigcomp_compartment *cc, 
			 char const *option);

/** Obtain a SigComp compartment with given name. */
struct sigcomp_compartment *
tport_sigcomp_compartment(tport_t *self, 
			  char const *name, int namelen,
			  int create_if_needed);

struct sigcomp_compartment *
tport_compartment_incref(struct sigcomp_compartment *cc);

void
tport_compartment_decref(struct sigcomp_compartment **pointer_to_cc);

/** Assign a SigComp compartment to a connection-oriented tport. */
int tport_sigcomp_assign(tport_t *self, struct sigcomp_compartment *);

/** Test if a SigComp compartment is assigned to a tport. */
int tport_has_sigcomp_assigned(tport_t const *self);

/** Accept SigComp message */
int tport_sigcomp_accept(tport_t *self, 
			 struct sigcomp_compartment *cc, 
			 msg_t *msg);

/** Get UDVM with which the request was delivered */
int tport_delivered_using_udvm(tport_t *tp, msg_t const *msg,
			       struct sigcomp_udvm **return_pointer_to_udvm,
			       int remove);

/** Shutdown SigComp compartment */
int tport_sigcomp_close(tport_t *self, 
			struct sigcomp_compartment *cc, 
			int how);

/** Set SigComp compartment lifetime. */
int tport_sigcomp_lifetime(tport_t *self, 
			   struct sigcomp_compartment *,
			   unsigned lifetime_in_ms,
			   int only_expand);


SOFIA_END_DECLS

#endif /* TPORT_H */