Loading...
Searching...
No Matches
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...

## Macros

#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 a master transport.
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.nosp@m..Pes.nosp@m.si@no.nosp@m.kia..nosp@m.com

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

## Macro Definition Documentation

## TP_MAGIC_T

#define TP_MAGIC_T

Type of transport-protocol-specific context.

See also
  Transport Magic

## Typedef Documentation

## tp_client_t

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.

## Enumeration Type Documentation

## anonymous enum

anonymous enum

Enumerator
TPORT_QUEUESIZE | Maximum number of messages in send queue.

## Function Documentation

## tport_by_name()

TPORT_DLL tport_t * tport_by_name | ( | tport_t const * | self,
|  | tp_name_t const * | tpn )

Get a transport corresponding to the name.

Get a transport corresponding to the name.

## tport_by_protocol()

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

Get a protocol corresponding to the protocol name.

Get a protocol corresponding to the protocol name.

## tport_convert_addr()

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_decref()

TPORT_DLL void tport_decref | ( | tport_t ** | tp | ) |

Destroy a transport reference.

Deprecated
  Use tport_unref().

## tport_delivered_with_comp()

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.

Get compressor context with which the request was delivered.

## tport_get_params()

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_has_sigcomp_assigned()

TPORT_DLL int tport_has_sigcomp_assigned | ( | tport_t const * | self | ) |

Test if a SigComp compartment is assigned to a tport.

Test if a SigComp compartment is assigned to a tport.

## tport_has_tls()

TPORT_DLL int tport_has_tls | ( | tport_t const * | self | ) |

Test if transport has TLS.

Test if transport has TLS.

## tport_hostport()

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.

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

## tport_ident()

TPORT_DLL char const * tport_ident | ( | tport_t const * | self | ) |

Get transport ident.

Get transport ident.

## tport_incref()

TPORT_DLL tport_t * tport_incref | ( | tport_t * | tp | ) |

Create a new transport reference.

Deprecated
  Use tport_ref().

Create a new transport reference.

## tport_is_clear_to_send()

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_is_closed()

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_is_connected()

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_is_dgram()

TPORT_DLL int tport_is_dgram | ( | tport_t const * | self | ) |

Return true if transport is dgram-based.

Return true if transport is dgram-based.

## tport_is_public()

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_is_reliable()

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_is_shutdown()

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_is_stream()

TPORT_DLL int tport_is_stream | ( | tport_t const * | self | ) |

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

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

## tport_is_verified()

TPORT_DLL int tport_is_verified | ( | tport_t const * | self | ) |

Test if transport provided a verified certificate chain (TLS only).

Test if transport provided a verified certificate chain (TLS only).

## tport_keepalive()

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

Initialize STUN keepalives.

Initialize STUN keepalives.

## tport_name_by_url()

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.

Create a transport name corresponding to the URL.

## tport_name_dup()

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_parent()

TPORT_DLL tport_t * tport_parent | ( | tport_t const * | self | ) |

Get primary transport (or self, if already parent).

Get primary transport (or self, if already parent).

## tport_pend()

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_primaries()

TPORT_DLL tport_t * tport_primaries | ( | tport_t const * | self | ) |

Get primary transports.

Get primary transports.

## tport_primary_by_name()

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.

Get transport by interface identifier and protocol name.

## tport_release()

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.

Do not wait for response anymore.

## tport_set_params()

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_shutdown()

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_sigcomp_accept()

TPORT_DLL int tport_sigcomp_accept | ( | tport_t * | self,
|  | struct sigcomp_compartment * | cc,
|  | msg_t * | msg )

Accept SigComp message.

Accept SigComp message.

## tport_sigcomp_assign()

TPORT_DLL int tport_sigcomp_assign | ( | tport_t * | self,
|  | struct sigcomp_compartment * | cc )

related

Assign a SigComp compartment to a connection-oriented tport.

Assign a SigComp compartment to a connection-oriented tport.

## tport_sigcomp_option()

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

Set SigComp option.

Set SigComp option.

## tport_subject_search()

TPORT_DLL int tport_subject_search | ( | char const * | subject,
|  | su_strlst_t const * | lst )

Check if the given subject string is found in su_strlst_t.

Check if the given subject string is found in su_strlst_t.

## tport_tbind()

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_tcreate()

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_tqsend()

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_tqueue()

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:

\n EINVAL Invalid argument(s).

\n ENOMEM Memory was exhausted.

\n ENOBUFS The transport object queue was full.

Deprecated
  Alternative interface will be provided in near future.

See also
  tport_tqsend()

## tport_tsend()

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()

Sofia-SIP 1.12.11devel - Copyright (C) 2006 Nokia Corporation. All rights reserved. Licensed under the terms of the GNU Lesser General Public License.