sofia-sip/tport.h File Reference

Transport interface. More...

#include <sofia-sip/su.h>
#include <sofia-sip/su_strlst.h>
#include <sofia-sip/su_wait.h>
#include <sofia-sip/msg.h>
#include <sofia-sip/url.h>
#include <sofia-sip/tport_tag.h>

Include dependency graph for tport.h:

Go to the source code of this file.

Data Structures
struct	tport_stack_class_t
	Interface towards stack. More...
struct	tp_name_t
	Transport name. More...
Defines
#define	TPORT_H
	Defined when <sofia-sip/tport.h> has been included.
#define	TP_MAGIC_T
	Type of transport-protocol-specific context.
#define	TP_AI_COMPRESSED
	Message is to be sent/received compressed.
#define	TP_AI_SECURE
	Message is to be sent/received on secure connection.
#define	TP_AI_SHUTDOWN
	Halfclose (shutdown(c, 1)) connection after sending message.
#define	TP_AI_CLOSE
	Close connection (shutdown(c, 2)) after sending message.
#define	TP_AI_ANY
	Address was inaddr_any.
#define	TPORT_HOSTPORTSIZE
	Maximum size of a host:port string, including final NUL.
Typedefs
typedef TP_STACK_T	tp_stack_t
	Type of stack object.
typedef TP_MAGIC_T	tp_magic_t
	Type of transport-protocol-specific context object.
typedef TP_CLIENT_T	tp_client_t
	Transaction object given as a reference to the transport.
typedef void	tport_pending_error_f (tp_stack_t *, tp_client_t *, tport_t *, msg_t *msg, int error)
	Callback to report error by pending requests.
Enumerations
enum	{ TPORT_QUEUESIZE }
Functions
TPORT_DLL 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 master transport.
TPORT_DLL int	tport_tbind (tport_t *self, tp_name_t const *tpn, char const *const transports[], tag_type_t tag, tag_value_t value,...)
	Bind transports to network.
TPORT_DLL int	tport_get_params (tport_t const *, tag_type_t tag, tag_value_t value,...)
	Get transport parameters.
TPORT_DLL int	tport_set_params (tport_t *self, tag_type_t tag, tag_value_t value,...)
	Set transport parameters.
TPORT_DLL void	tport_destroy (tport_t *tport)
	Destroy transport(s).
TPORT_DLL int	tport_shutdown (tport_t *tport, int how)
	Shutdown a transport connection.
TPORT_DLL tport_t *	tport_ref (tport_t *tp)
	Create a new reference to a transport object.
TPORT_DLL void	tport_unref (tport_t *tp)
	Destroy reference to a transport object.
TPORT_DLL tport_t *	tport_incref (tport_t *tp)
	Create a new transport reference.
TPORT_DLL void	tport_decref (tport_t **tp)
	Destroy a transport reference.
TPORT_DLL tport_t *	tport_tsend (tport_t *, msg_t *, tp_name_t const *, tag_type_t, tag_value_t,...)
	Send a message using transport.
TPORT_DLL int	tport_tqueue (tport_t *, msg_t *, tag_type_t, tag_value_t,...)
	Queue a message to transport.
TPORT_DLL isize_t	tport_queuelen (tport_t const *self)
	Return number of queued messages.
TPORT_DLL int	tport_tqsend (tport_t *, msg_t *, msg_t *, tag_type_t, tag_value_t,...)
	Send a queued message (and queue another, if required).
TPORT_DLL int	tport_stall (tport_t *self)
	Stop reading from socket until tport_continue() is called.
TPORT_DLL int	tport_continue (tport_t *self)
	Continue reading from socket.
TPORT_DLL int	tport_pend (tport_t *self, msg_t *msg, tport_pending_error_f *callback, tp_client_t *client)
	Mark message as waiting for a response.
TPORT_DLL int	tport_release (tport_t *self, int pendd, msg_t *msg, msg_t *reply, tp_client_t *client, int still_pending)
	Do not wait for response anymore.
TPORT_DLL int	tport_is_master (tport_t const *self)
	Return true if transport is master.
TPORT_DLL int	tport_is_primary (tport_t const *self)
	Return true if transport is primary.
TPORT_DLL int	tport_is_public (tport_t const *self)
	Return nonzero if transport is public.
TPORT_DLL int	tport_is_secondary (tport_t const *self)
	Return true if transport is secondary.
TPORT_DLL int	tport_is_reliable (tport_t const *tport)
	Return true if transport is reliable, false otherwise.
TPORT_DLL int	tport_is_stream (tport_t const *tport)
	Return true if transport is a stream (no message boundaries).
TPORT_DLL int	tport_is_dgram (tport_t const *tport)
	Return true if transport is dgram-based.
TPORT_DLL int	tport_has_ip4 (tport_t const *tport)
	Return true if transport supports IPv4.
TPORT_DLL int	tport_has_ip6 (tport_t const *tport)
	Return true if transport supports IPv6.
TPORT_DLL int	tport_is_udp (tport_t const *self)
	Test if transport is udp.
TPORT_DLL int	tport_is_tcp (tport_t const *self)
	Test if transport is tcp.
TPORT_DLL int	tport_has_tls (tport_t const *tport)
	Test if transport has TLS.
TPORT_DLL int	tport_is_verified (tport_t const *tport)
	Test if transport provided a verified certificate chain (TLS only).
TPORT_DLL int	tport_is_updating (tport_t const *self)
	Return true if transport is being updated.
TPORT_DLL int	tport_is_closed (tport_t const *self)
	Test if transport has been closed.
TPORT_DLL int	tport_is_shutdown (tport_t const *self)
	Test if transport has been shut down.
TPORT_DLL int	tport_is_connected (tport_t const *self)
	Test if transport is connected.
TPORT_DLL int	tport_is_clear_to_send (tport_t const *self)
	Test if transport can be used to send message.
TPORT_DLL void	tport_set_magic (tport_t *self, tp_magic_t *magic)
	Set transport magic.
TPORT_DLL tp_magic_t *	tport_magic (tport_t const *tport)
	Get transport magic.
TPORT_DLL tp_name_t const *	tport_name (tport_t const *tport)
	Get transport name.
TPORT_DLL su_addrinfo_t const *	tport_get_address (tport_t const *tport)
	Get transport address list.
TPORT_DLL char const *	tport_ident (tport_t const *self)
	Get transport ident.
TPORT_DLL tport_t *	tport_parent (tport_t const *self)
	Get primary transport (or self, if already parent).
TPORT_DLL int	tport_flush (tport_t *)
	Flush idle connections.
TPORT_DLL tport_t *	tport_primaries (tport_t const *tport)
	Get primary transports.
TPORT_DLL tport_t *	tport_next (tport_t const *tport)
	Get next transport.
TPORT_DLL tport_t *	tport_secondary (tport_t const *tport)
	Get secondary transports.
TPORT_DLL tport_t *	tport_by_protocol (tport_t const *self, char const *proto)
	Get a protocol corresponding to the protocol name.
TPORT_DLL tport_t *	tport_primary_by_name (tport_t const *self, tp_name_t const *tpn)
	Get transport by interface identifier and protocol name.
TPORT_DLL tport_t *	tport_by_name (tport_t const *self, tp_name_t const *)
	Get a transport corresponding to the name.
TPORT_DLL int	tport_name_by_url (su_home_t *, tp_name_t *, url_string_t const *us)
	Create a transport name corresponding to the URL.
TPORT_DLL tport_t *	tport_delivered_by (tport_t const *tp, msg_t const *msg)
	Return source transport object for delivered message.
TPORT_DLL int	tport_delivered_from (tport_t *tp, msg_t const *msg, tp_name_t name[1])
	Return source transport name for delivered message.
TPORT_DLL su_strlst_t const *	tport_delivered_from_subjects (tport_t *tp, msg_t const *msg)
	Return TLS Subjects provided by the source transport.
TPORT_DLL int	tport_subject_search (char const *, su_strlst_t const *)
	Check if the given subject string is found in su_strlst_t.
TPORT_DLL int	tport_name_is_resolved (tp_name_t const *)
	Check if transport named is already resolved.
TPORT_DLL int	tport_name_dup (su_home_t *, tp_name_t *dst, tp_name_t const *src)
	Duplicate a transport name.
TPORT_DLL int	tport_convert_addr (su_home_t *home, tp_name_t *tpn, char const *protoname, char const *canon, su_sockaddr_t const *su)
	Convert a socket address to a transport name.
TPORT_DLL char *	tport_hostport (char buf[], isize_t bufsize, su_sockaddr_t const *su, int with_port)
	Print host and port separated with ':' to a string.
TPORT_DLL int	tport_keepalive (tport_t *tp, su_addrinfo_t const *ai, tag_type_t tag, tag_value_t value,...)
	Initialize STUN keepalives.
TPORT_DLL int	tport_can_send_sigcomp (tport_t const *self)
	Check if transport can send compressed messages.
TPORT_DLL int	tport_can_recv_sigcomp (tport_t const *self)
	Check if transport can receive compressed messages.
TPORT_DLL int	tport_has_compression (tport_t const *self, char const *comp)
	Check if transport supports named compression.
TPORT_DLL int	tport_set_compression (tport_t *self, char const *comp)
	Set the compression protocol as comp.
TPORT_DLL int	tport_sigcomp_option (tport_t const *self, struct sigcomp_compartment *cc, char const *option)
	Set SigComp option.
TPORT_DLL struct sigcomp_compartment *	tport_sigcomp_compartment (tport_t *self, char const *name, isize_t namelen, int create_if_needed)
	Obtain a SigComp compartment with given name.
TPORT_DLL int	tport_sigcomp_assign (tport_t *self, struct sigcomp_compartment *)
	Assign a SigComp compartment to a connection-oriented tport.
TPORT_DLL int	tport_has_sigcomp_assigned (tport_t const *self)
	Test if a SigComp compartment is assigned to a tport.
TPORT_DLL int	tport_sigcomp_accept (tport_t *self, struct sigcomp_compartment *cc, msg_t *msg)
	Accept SigComp message.
TPORT_DLL int	tport_delivered_with_comp (tport_t *tp, msg_t const *msg, tport_compressor_t **return_compressor)
	Get compressor context with which the request was delivered.
TPORT_DLL int	tport_sigcomp_close (tport_t *self, struct sigcomp_compartment *cc, int how)
	Shutdown SigComp compartment.
TPORT_DLL int	tport_sigcomp_lifetime (tport_t *self, struct sigcomp_compartment *, unsigned lifetime_in_ms, int only_expand)
	Set SigComp compartment lifetime.

---

Detailed Description

Transport interface.

Author:

Pekka Pessi <Pekka.Pessi@nokia-email.address.hidden>

Date:

Created: Thu Jun 29 15:58:06 2000 ppessi

---

Define Documentation

#define TP_MAGIC_T

Type of transport-protocol-specific context.

See also:

Transport Magic

#define TPORT_H

Defined when <sofia-sip/tport.h> has been included.

#define TPORT_HOSTPORTSIZE

Maximum size of a host:port string, including final NUL.

---

Typedef Documentation

typedef TP_CLIENT_T tp_client_t

Transaction object given as a reference to the transport.

This type is used when transport reports errors with pending requests.

typedef TP_MAGIC_T tp_magic_t

Type of transport-protocol-specific context object.

typedef void tport_pending_error_f(tp_stack_t *, tp_client_t *, tport_t *, msg_t *msg, int error)

Callback to report error by pending requests.

---

Enumeration Type Documentation

anonymous enum

Enumerator:

TPORT_QUEUESIZE

Maximum number of messages in send queue.

---

Function Documentation

TPORT_DLL tport_t* tport_by_protocol	(	tport_t const *	self,
		char const *	proto
	)

Get a protocol corresponding to the protocol name.

TPORT_DLL int tport_continue

(

tport_t *

self

)

Continue reading from socket.

TPORT_DLL int tport_convert_addr	(	su_home_t *	home,
		tp_name_t *	tpn,
		char const *	protoname,
		char const *	canon,
		su_sockaddr_t const *	su
	)

Convert a socket address to a transport name.

Convert a socket address to a transport name.

Return values:

	0	when successful
	-1	upon an error

TPORT_DLL void tport_decref

(

tport_t **

ttp

)

Destroy a transport reference.

Deprecated:

Use tport_unref().

TPORT_DLL void tport_destroy

(

tport_t *

self

)

Destroy transport(s).

TPORT_DLL int tport_flush

(

tport_t *

tp

)

Flush idle connections.

TPORT_DLL su_addrinfo_t const* tport_get_address

(

tport_t const *

self

)

Get transport address list.

TPORT_DLL int tport_get_params	(	tport_t const *	self,
		tag_type_t	tag,
		tag_value_t	value,
			...
	)

Get transport parameters.

Parameters:

	self	pointer to a transport object
	tag,value,...	list of tags

Related Tags:

TPTAG_MTU_REF(), TPTAG_QUEUESIZE_REF(), TPTAG_IDLE_REF(), TPTAG_TIMEOUT_REF(), TPTAG_KEEPALIVE_REF(), TPTAG_PINGPONG_REF(), TPTAG_PONG2PING_REF(), TPTAG_DEBUG_DROP_REF(), TPTAG_THRPSIZE_REF(), TPTAG_THRPRQSIZE_REF(), TPTAG_SIGCOMP_LIFETIME_REF(), TPTAG_CONNECT_REF(), TPTAG_SDWN_ERROR_REF(), TPTAG_REUSE_REF(), TPTAG_STUN_SERVER_REF(), TPTAG_PUBLIC_REF() and TPTAG_TOS_REF().

TPORT_DLL int tport_has_sigcomp_assigned

(

tport_t const *

self

)

Test if a SigComp compartment is assigned to a tport.

TPORT_DLL int tport_has_tls

(

tport_t const *

self

)

Test if transport has TLS.

TPORT_DLL char* tport_hostport	(	char	buf[],
		isize_t	bufsize,
		su_sockaddr_t const *	su,
		int	with_port_and_brackets
	)

Print host and port separated with ':' to a string.

TPORT_DLL char const* tport_ident

(

tport_t const *

self

)

Get transport ident.

TPORT_DLL tport_t* tport_incref

(

tport_t *

tp

)

Create a new transport reference.

Deprecated:

Use tport_ref().

TPORT_DLL int tport_is_clear_to_send

(

tport_t const *

self

)

Test if transport can be used to send message.

Since:

New in 1.12.7.

TPORT_DLL int tport_is_closed

(

tport_t const *

self

)

[inline]

Test if transport has been closed.

Since:

New in 1.12.4.

New in 1.12.4

TPORT_DLL int tport_is_connected

(

tport_t const *

self

)

Test if transport is connected.

Since:

New in 1.12.5.

Test if transport is connected.

Since:

New in 1.12.5.

TPORT_DLL int tport_is_dgram

(

tport_t const *

self

)

Return true if transport is dgram-based.

TPORT_DLL int tport_is_master

(

tport_t const *

self

)

Return true if transport is master.

TPORT_DLL int tport_is_primary

(

tport_t const *

self

)

Return true if transport is primary.

TPORT_DLL int tport_is_public

(

tport_t const *

self

)

Return nonzero if transport is public.

Return nonzero if transport is public.

The return valu is the tport_via enum.

See also:

TPTAG_PUBLIC(), enum tport_via.

TPORT_DLL int tport_is_reliable

(

tport_t const *

self

)

Return true if transport is reliable, false otherwise.

Return true if transport is reliable, false otherwise.

(Note that this is part of external API).

TPORT_DLL int tport_is_secondary

(

tport_t const *

self

)

Return true if transport is secondary.

TPORT_DLL int tport_is_shutdown

(

tport_t const *

self

)

[inline]

Test if transport has been shut down.

Since:

New in 1.12.4.

New in 1.12.4

TPORT_DLL int tport_is_stream

(

tport_t const *

self

)

Return true if transport is a stream (no message boundaries).

TPORT_DLL int tport_is_tcp

(

tport_t const *

self

)

Test if transport is tcp.

TPORT_DLL int tport_is_udp

(

tport_t const *

self

)

Test if transport is udp.

TPORT_DLL int tport_is_updating

(

tport_t const *

self

)

Return true if transport is being updated.

TPORT_DLL int tport_keepalive	(	tport_t *	tp,
		su_addrinfo_t const *	ai,
		tag_type_t	tag,
		tag_value_t	value,
			...
	)

Initialize STUN keepalives.

TPORT_DLL tp_magic_t* tport_magic

(

tport_t const *

self

)

Get transport magic.

TPORT_DLL tp_name_t const* tport_name

(

tport_t const *

self

)

Get transport name.

TPORT_DLL int tport_name_by_url	(	su_home_t *	home,
		tp_name_t *	tpn,
		url_string_t const *	us
	)

Create a transport name corresponding to the URL.

TPORT_DLL int tport_name_dup	(	su_home_t *	home,
		tp_name_t *	dst,
		tp_name_t const *	src
	)

Duplicate a transport name.

Duplicate a transport name.

The tport_name_dup() function copies strings belonging to the transport name. It returns the copied strings via the dst transport name structure. The memory block required for copies is allocated from the memory home. Please note that only one memory block is allocated, so the memory can be reclainmed only by deinitializing the memory home itself.

Return values:

	0	when successful
	-1	upon an error

TPORT_DLL int tport_pend	(	tport_t *	self,
		msg_t *	msg,
		tport_pending_error_f *	callback,
		tp_client_t *	client
	)

Mark message as waiting for a response.

Returns:

Positive integer, or -1 upon an error.

TPORT_DLL tport_t* tport_primary_by_name	(	tport_t const *	tp,
		tp_name_t const *	tpn
	)

Get transport by interface identifier and protocol name.

TPORT_DLL isize_t tport_queuelen

(

tport_t const *

self

)

Return number of queued messages.

TPORT_DLL tport_t* tport_ref

(

tport_t *

tp

)

Create a new reference to a transport object.

TPORT_DLL int tport_release	(	tport_t *	self,
		int	pendd,
		msg_t *	msg,
		msg_t *	reply,
		tp_client_t *	client,
		int	still_pending
	)

Do not wait for response anymore.

TPORT_DLL tport_t* tport_secondary

(

tport_t const *

self

)

Get secondary transports.

TPORT_DLL int tport_set_compression	(	tport_t *	self,
		char const *	comp
	)

Set the compression protocol as comp.

TPORT_DLL void tport_set_magic	(	tport_t *	self,
		tp_magic_t *	magic
	)

Set transport magic.

TPORT_DLL int tport_set_params	(	tport_t *	self,
		tag_type_t	tag,
		tag_value_t	value,
			...
	)

Set transport parameters.

Parameters:

	self	pointer to a transport object
	tag,value,...	list of tags

Related Tags:

TPTAG_MTU(), TPTAG_QUEUESIZE(), TPTAG_IDLE(), TPTAG_TIMEOUT(), TPTAG_KEEPALIVE(), TPTAG_PINGPONG(), TPTAG_PONG2PING(), TPTAG_DEBUG_DROP(), TPTAG_THRPSIZE(), TPTAG_THRPRQSIZE(), TPTAG_SIGCOMP_LIFETIME(), TPTAG_CONNECT(), TPTAG_SDWN_ERROR(), TPTAG_REUSE(), TPTAG_STUN_SERVER(), and TPTAG_TOS().

TPORT_DLL int tport_shutdown	(	tport_t *	self,
		int	how
	)

Shutdown a transport connection.

Shutdown a transport connection.

The tport_shutdown() shuts down a full-duplex transport connection partially or completely. If how is 0, the further incoming data is shut down. If how is 1, further outgoing data is shut down. If how is 2, both incoming and outgoing traffic is shut down.

TPORT_DLL int tport_sigcomp_assign	(	tport_t *	self,
		struct sigcomp_compartment *	cc
	)			[related]

Assign a SigComp compartment to a connection-oriented tport.

TPORT_DLL struct sigcomp_compartment* tport_sigcomp_compartment	(	tport_t *	self,
		char const *	name,
		isize_t	namelen,
		int	create_if_needed
	)			[read]

Obtain a SigComp compartment with given name.

TPORT_DLL int tport_sigcomp_lifetime	(	tport_t *	self,
		struct sigcomp_compartment *	,
		unsigned	lifetime_in_ms,
		int	only_expand
	)

Set SigComp compartment lifetime.

TPORT_DLL int tport_sigcomp_option	(	tport_t const *	self,
		struct sigcomp_compartment *	cc,
		char const *	option
	)

Set SigComp option.

TPORT_DLL int tport_stall

(

tport_t *

self

)

Stop reading from socket until tport_continue() is called.

TPORT_DLL int tport_tbind	(	tport_t *	self,
		tp_name_t const *	tpn,
		char const *const	transports[],
		tag_type_t	tag,
		tag_value_t	value,
			...
	)

Bind transports to network.

Bind transports to network.

Parameters:

	self	pointer to a transport object
	tpn	desired transport address
	transports	list of protocol names supported by stack
	tag,value,...	tagged argument list

Related Tags:

TPTAG_SERVER(), TPTAG_PUBLIC(), TPTAG_IDENT(), TPTAG_HTTP_CONNECT(), TPTAG_CERTIFICATE(), TPTAG_TLS_VERSION(), TPTAG_TLS_VERIFY_POLICY, and tags used with tport_set_params(), especially TPTAG_QUEUESIZE().

TPORT_DLL tport_t* tport_tcreate	(	tp_stack_t *	stack,
		tp_stack_class_t const *	tpac,
		su_root_t *	root,
		tag_type_t	tag,
		tag_value_t	value,
			...
	)

Create master transport.

Create master transport.

Master transport object is used to bind the protocol using transport with actual transport objects corresponding to TCP, UDP, etc.

See also:

tport_tbind()

Related Tags:

TPTAG_LOG(), TPTAG_DUMP(), tags used with tport_set_params(), especially TPTAG_QUEUESIZE().

TPORT_DLL int tport_tqsend	(	tport_t *	self,
		msg_t *	msg,
		msg_t *	next,
		tag_type_t	tag,
		tag_value_t	value,
			...
	)

Send a queued message (and queue another, if required).

The function tport_tqsend() sends a message to the transport.

Deprecated:

Alternative interface will be provided in near future.

TPORT_DLL int tport_tqueue	(	tport_t *	self,
		msg_t *	msg,
		tag_type_t	tag,
		tag_value_t	value,
			...
	)

Queue a message to transport.

The tport_tqueue() function queues a message in the send queue. It is used by an (server) application that is required to send (response) messages in certain order. For example, a HTTP server or proxy may receive multiple requests from a single TCP connection. The server is required to answer to the requests in same order as they are received. The responses are, however, sometimes generated asynchronously, that is, a response to a later request may be ready earlier. For that purpose, the HTTP protocol stack queues an empty response message immediately upon receiving a request. Other messages cannot be sent before the queued one.

The function tport_tqsend() is used to send the completed response message.

Parameters:

	self	pointer to transport object
	msg	message to be inserted into queue
	tag,value,...	tagged argument list

Related Tags:

Currently none.

Return values:

	0	when successful
	-1	upon an error

Errors:

EINVAL Invalid argument(s).

ENOMEM Memory was exhausted.

ENOBUFS The transport object queue was full.

Deprecated:

Alternative interface will be provided in near future.

See also:

tport_tqsend()

TPORT_DLL tport_t* tport_tsend	(	tport_t *	self,
		msg_t *	msg,
		tp_name_t const *	_tpn,
		tag_type_t	tag,
		tag_value_t	value,
			...
	)

Send a message using transport.

Send a message using transport.

The function tport_tsend() sends a message using the transport self.

Related Tags:

TPTAG_MTU(), TPTAG_REUSE(), TPTAG_CLOSE_AFTER(), TPTAG_SDWN_AFTER(), TPTAG_FRESH(), TPTAG_COMPARTMENT(), TPTAG_X509_SUBJECT()

TPORT_DLL void tport_unref

(

tport_t *

tp

)

Destroy reference to a transport object.