Network Routines
[Brought To You By APR]

Collaboration diagram for Network Routines:

Modules
	IP Protocol Definitions for use when creating sockets
Defines
#define	SWITCH_SO_LINGER   1
#define	SWITCH_SO_KEEPALIVE   2
#define	SWITCH_SO_DEBUG   4
#define	SWITCH_SO_NONBLOCK   8
#define	SWITCH_SO_REUSEADDR   16
#define	SWITCH_SO_SNDBUF   64
#define	SWITCH_SO_RCVBUF   128
#define	SWITCH_SO_DISCONNECTED   256
#define	SWITCH_SO_TCP_NODELAY   512
#define	SWITCH_INET   AF_INET
#define	SWITCH_UNSPEC   0
Typedefs
typedef apr_socket_t	switch_socket_t
typedef apr_sockaddr_t	switch_sockaddr_t
Enumerations
enum	switch_shutdown_how_e { SWITCH_SHUTDOWN_READ, SWITCH_SHUTDOWN_WRITE, SWITCH_SHUTDOWN_READWRITE }
Functions
switch_status_t	switch_socket_create (switch_socket_t **new_sock, int family, int type, int protocol, switch_memory_pool_t *pool)
switch_status_t	switch_socket_shutdown (switch_socket_t *sock, switch_shutdown_how_e how)
switch_status_t	switch_socket_close (switch_socket_t *sock)
switch_status_t	switch_socket_bind (switch_socket_t *sock, switch_sockaddr_t *sa)
switch_status_t	switch_socket_listen (switch_socket_t *sock, int32_t backlog)
switch_status_t	switch_socket_accept (switch_socket_t **new_sock, switch_socket_t *sock, switch_memory_pool_t *pool)
switch_status_t	switch_socket_connect (switch_socket_t *sock, switch_sockaddr_t *sa)
uint16_t	switch_sockaddr_get_port (switch_sockaddr_t *sa)
const char *	switch_get_addr (char *buf, switch_size_t len, switch_sockaddr_t *in)
int32_t	switch_sockaddr_get_family (switch_sockaddr_t *sa)
switch_status_t	switch_sockaddr_ip_get (char **addr, switch_sockaddr_t *sa)
int	switch_sockaddr_equal (const switch_sockaddr_t *sa1, const switch_sockaddr_t *sa2)
switch_status_t	switch_sockaddr_info_get (switch_sockaddr_t **sa, const char *hostname, int32_t family, switch_port_t port, int32_t flags, switch_memory_pool_t *pool)
switch_status_t	switch_sockaddr_create (switch_sockaddr_t **sa, switch_memory_pool_t *pool)
switch_status_t	switch_socket_send (switch_socket_t *sock, const char *buf, switch_size_t *len)
switch_status_t	switch_socket_sendto (switch_socket_t *sock, switch_sockaddr_t *where, int32_t flags, const char *buf, switch_size_t *len)
switch_status_t	switch_socket_send_nonblock (switch_socket_t *sock, const char *buf, switch_size_t *len)
switch_status_t	switch_socket_recvfrom (switch_sockaddr_t *from, switch_socket_t *sock, int32_t flags, char *buf, size_t *len)
switch_status_t	switch_socket_atmark (switch_socket_t *sock, int *atmark)
switch_status_t	switch_socket_recv (switch_socket_t *sock, char *buf, switch_size_t *len)
switch_status_t	switch_socket_opt_set (switch_socket_t *sock, int32_t opt, int32_t on)
switch_status_t	switch_socket_timeout_set (switch_socket_t *sock, switch_interval_time_t t)
switch_status_t	switch_mcast_join (switch_socket_t *sock, switch_sockaddr_t *join, switch_sockaddr_t *iface, switch_sockaddr_t *source)
switch_status_t	switch_mcast_hops (switch_socket_t *sock, uint8_t ttl)
switch_status_t	switch_mcast_loopback (switch_socket_t *sock, uint8_t opt)

---

Define Documentation

#define SWITCH_INET   AF_INET

Not all platforms have these defined, so we'll define them here The default values come from FreeBSD 4.1.1

Definition at line 1044 of file switch_apr.h.

#define SWITCH_SO_DEBUG   4

Definition at line 1030 of file switch_apr.h.

#define SWITCH_SO_DISCONNECTED   256

Definition at line 1035 of file switch_apr.h.

#define SWITCH_SO_KEEPALIVE   2

Definition at line 1029 of file switch_apr.h.

#define SWITCH_SO_LINGER   1

Definition at line 1028 of file switch_apr.h.

#define SWITCH_SO_NONBLOCK   8

Definition at line 1031 of file switch_apr.h.

Referenced by do_flush(), init_nat_monitor(), switch_rtp_clear_flag(), switch_rtp_set_flag(), switch_rtp_set_local_address(), switch_rtp_udptl_mode(), and switch_stun_lookup().

#define SWITCH_SO_RCVBUF   128

Definition at line 1034 of file switch_apr.h.

#define SWITCH_SO_REUSEADDR   16

Definition at line 1032 of file switch_apr.h.

Referenced by enable_local_rtcp_socket(), init_nat_monitor(), and switch_rtp_set_local_address().

#define SWITCH_SO_SNDBUF   64

Definition at line 1033 of file switch_apr.h.

#define SWITCH_SO_TCP_NODELAY   512

Definition at line 1036 of file switch_apr.h.

#define SWITCH_UNSPEC   0

Let the system decide which address family to use

Definition at line 1052 of file switch_apr.h.

Referenced by enable_local_rtcp_socket(), enable_remote_rtcp_socket(), init_nat_monitor(), switch_ivr_activate_unicast(), switch_rtp_activate_stun_ping(), switch_rtp_set_local_address(), switch_rtp_set_remote_address(), switch_stun_host_lookup(), and switch_stun_lookup().

---

Typedef Documentation

typedef struct apr_sockaddr_t switch_sockaddr_t

Freeswitch's socket address type, used to ensure protocol independence

Definition at line 1059 of file switch_apr.h.

typedef struct apr_socket_t switch_socket_t

A structure to represent sockets

Definition at line 1056 of file switch_apr.h.

---

Enumeration Type Documentation

enum switch_shutdown_how_e

Enumerator:

SWITCH_SHUTDOWN_READ	no longer allow read request
SWITCH_SHUTDOWN_WRITE	no longer allow write requests
SWITCH_SHUTDOWN_READWRITE	no longer allow read or write requests

Definition at line 1061 of file switch_apr.h.

                      {
                 SWITCH_SHUTDOWN_READ,     /**< no longer allow read request */
                 SWITCH_SHUTDOWN_WRITE,    /**< no longer allow write requests */
                 SWITCH_SHUTDOWN_READWRITE /**< no longer allow read or write requests */
         } switch_shutdown_how_e;

---

Function Documentation

const char* switch_get_addr	(	char *	buf,
		switch_size_t	len,
		switch_sockaddr_t *	in
	)

Definition at line 829 of file switch_apr.c.

References get_addr(), get_addr6(), and SWITCH_BLANK_STRING.

Referenced by enable_local_rtcp_socket(), enable_remote_rtcp_socket(), handle_ice(), rtp_common_read(), rtp_common_write(), and switch_stun_host_lookup().

{
        if (!in) {
                return SWITCH_BLANK_STRING;
        }

        if (in->family == AF_INET) {
                return get_addr(buf, len, (struct sockaddr *) &in->sa, in->salen);
        }

        return get_addr6(buf, len, (struct sockaddr_in6 *) &in->sa, in->salen);
}

switch_status_t switch_mcast_hops	(	switch_socket_t *	sock,
		uint8_t	ttl
	)

Set the Multicast Time to Live (ttl) for a multicast transmission.

Parameters:

	sock	The socket to set the multicast ttl
	ttl	Time to live to Assign. 0-255, default=1

Remarks:

If the TTL is 0, packets will only be seen by sockets on the local machine, and only when multicast loopback is enabled.

Definition at line 817 of file switch_apr.c.

{
        return apr_mcast_hops(sock, ttl);
}

switch_status_t switch_mcast_join	(	switch_socket_t *	sock,
		switch_sockaddr_t *	join,
		switch_sockaddr_t *	iface,
		switch_sockaddr_t *	source
	)

Join a Multicast Group

Parameters:

	sock	The socket to join a multicast group
	join	The address of the multicast group to join
	iface	Address of the interface to use. If NULL is passed, the default multicast interface will be used. (OS Dependent)
	source	Source Address to accept transmissions from (non-NULL implies Source-Specific Multicast)

Definition at line 812 of file switch_apr.c.

Referenced by init_nat_monitor().

{
        return apr_mcast_join(sock, join, iface, source);
}

switch_status_t switch_mcast_loopback	(	switch_socket_t *	sock,
		uint8_t	opt
	)

Definition at line 822 of file switch_apr.c.

{
        return apr_mcast_loopback(sock, opt);
}

switch_status_t switch_sockaddr_create	(	switch_sockaddr_t **	sa,
		switch_memory_pool_t *	pool
	)

Definition at line 764 of file switch_apr.c.

References switch_assert, and SWITCH_STATUS_SUCCESS.

Referenced by switch_rtp_create().

{
        switch_sockaddr_t *new_sa;
        unsigned short family = APR_INET;

        new_sa = apr_pcalloc(pool, sizeof(apr_sockaddr_t));
        switch_assert(new_sa);
        new_sa->pool = pool;
        memset(new_sa, 0, sizeof(*new_sa));

    new_sa->family = family;
    new_sa->sa.sin.sin_family = family;

    new_sa->salen = sizeof(struct sockaddr_in);
    new_sa->addr_str_len = 16;
    new_sa->ipaddr_ptr = &(new_sa->sa.sin.sin_addr);
    new_sa->ipaddr_len = sizeof(struct in_addr);

        *sa = new_sa;
        return SWITCH_STATUS_SUCCESS;
}

int switch_sockaddr_equal	(	const switch_sockaddr_t *	sa1,
		const switch_sockaddr_t *	sa2
	)

Definition at line 807 of file switch_apr.c.

{
        return apr_sockaddr_equal(sa1, sa2);
}

int32_t switch_sockaddr_get_family

(

switch_sockaddr_t *

sa

)

Definition at line 847 of file switch_apr.c.

Referenced by enable_local_rtcp_socket(), enable_remote_rtcp_socket(), switch_rtp_set_local_address(), and switch_rtp_set_remote_address().

{
        return sa->family;
}

uint16_t switch_sockaddr_get_port

(

switch_sockaddr_t *

sa

)

Definition at line 842 of file switch_apr.c.

Referenced by enable_local_rtcp_socket(), handle_ice(), rtp_common_read(), and rtp_common_write().

{
        return sa->port;
}

switch_status_t switch_sockaddr_info_get	(	switch_sockaddr_t **	sa,
		const char *	hostname,
		int32_t	family,
		switch_port_t	port,
		int32_t	flags,
		switch_memory_pool_t *	pool
	)

Create apr_sockaddr_t from hostname, address family, and port.

Parameters:

	sa	The new apr_sockaddr_t.
	hostname	The hostname or numeric address string to resolve/parse, or NULL to build an address that corresponds to 0.0.0.0 or ::
	family	The address family to use, or SWITCH_UNSPEC if the system should decide.
	port	The port number.
	flags	Special processing flags: APR_IPV4_ADDR_OK first query for IPv4 addresses; only look for IPv6 addresses if the first query failed; only valid if family is APR_UNSPEC and hostname isn't NULL; mutually exclusive with APR_IPV6_ADDR_OK APR_IPV6_ADDR_OK first query for IPv6 addresses; only look for IPv4 addresses if the first query failed; only valid if family is APR_UNSPEC and hostname isn't NULL and APR_HAVE_IPV6; mutually exclusive with APR_IPV4_ADDR_OK
	pool	The pool for the apr_sockaddr_t and associated storage.

Definition at line 786 of file switch_apr.c.

Referenced by enable_local_rtcp_socket(), enable_remote_rtcp_socket(), init_nat_monitor(), switch_ivr_activate_unicast(), switch_rtp_activate_stun_ping(), switch_rtp_set_local_address(), switch_rtp_set_remote_address(), switch_stun_host_lookup(), and switch_stun_lookup().

{
        return apr_sockaddr_info_get(sa, hostname, family, port, flags, pool);
}

switch_status_t switch_sockaddr_ip_get	(	char **	addr,
		switch_sockaddr_t *	sa
	)

Definition at line 802 of file switch_apr.c.

{
        return apr_sockaddr_ip_get(addr, sa);
}

switch_status_t switch_socket_accept	(	switch_socket_t **	new_sock,
		switch_socket_t *	sock,
		switch_memory_pool_t *	pool
	)

Accept a new connection request

Parameters:

	new_sock	A copy of the socket that is connected to the socket that made the connection request. This is the socket which should be used for all future communication.
	sock	The socket we are listening on.
	pool	The pool for the new socket.

Definition at line 698 of file switch_apr.c.

{
        return apr_socket_accept(new_sock, sock, pool);
}

switch_status_t switch_socket_atmark	(	switch_socket_t *	sock,
		int *	atmark
	)

Definition at line 852 of file switch_apr.c.

{
        return apr_socket_atmark(sock, atmark);
}

switch_status_t switch_socket_bind	(	switch_socket_t *	sock,
		switch_sockaddr_t *	sa
	)

Bind the socket to its associated port

Parameters:

	sock	The socket to bind
	sa	The socket address to bind to

Remarks:

This may be where we will find out if there is any other process using the selected port.

Definition at line 688 of file switch_apr.c.

Referenced by enable_local_rtcp_socket(), init_nat_monitor(), switch_ivr_activate_unicast(), switch_rtp_set_local_address(), and switch_stun_lookup().

{
        return apr_socket_bind(sock, sa);
}

switch_status_t switch_socket_close

(

switch_socket_t *

sock

)

Close a socket.

Parameters:

sock

The socket to close

Definition at line 683 of file switch_apr.c.

Referenced by enable_local_rtcp_socket(), enable_remote_rtcp_socket(), init_nat_monitor(), switch_ivr_deactivate_unicast(), switch_rtp_destroy(), switch_rtp_set_local_address(), switch_rtp_set_remote_address(), switch_rtp_udptl_mode(), and switch_stun_lookup().

{
        return apr_socket_close(sock);
}

switch_status_t switch_socket_connect	(	switch_socket_t *	sock,
		switch_sockaddr_t *	sa
	)

Issue a connection request to a socket either on the same machine or a different one.

Parameters:

	sock	The socket we wish to use for our side of the connection
	sa	The address of the machine we wish to connect to.

Definition at line 703 of file switch_apr.c.

{
        return apr_socket_connect(sock, sa);
}

switch_status_t switch_socket_create	(	switch_socket_t **	new_sock,
		int	family,
		int	type,
		int	protocol,
		switch_memory_pool_t *	pool
	)

Create a socket.

Parameters:

	new_sock	The new socket that has been set up.
	family	The address family of the socket (e.g., SWITCH_INET).
	type	The type of the socket (e.g., SOCK_STREAM).
	protocol	The protocol of the socket (e.g., SWITCH_PROTO_TCP).
	pool	The pool to use

Definition at line 673 of file switch_apr.c.

Referenced by enable_local_rtcp_socket(), enable_remote_rtcp_socket(), init_nat_monitor(), switch_ivr_activate_unicast(), switch_rtp_set_local_address(), switch_rtp_set_remote_address(), and switch_stun_lookup().

{
        return apr_socket_create(new_sock, family, type, protocol, pool);
}

switch_status_t switch_socket_listen	(	switch_socket_t *	sock,
		int32_t	backlog
	)

Listen to a bound socket for connections.

Parameters:

	sock	The socket to listen on
	backlog	The number of outstanding connections allowed in the sockets listen queue. If this value is less than zero, the listen queue size is set to zero.

Definition at line 693 of file switch_apr.c.

{
        return apr_socket_listen(sock, backlog);
}

switch_status_t switch_socket_opt_set	(	switch_socket_t *	sock,
		int32_t	opt,
		int32_t	on
	)

Setup socket options for the specified socket

Parameters:

	sock	The socket to set up.
	opt	The option we would like to configure. One of: APR_SO_DEBUG -- turn on debugging information APR_SO_KEEPALIVE -- keep connections active APR_SO_LINGER -- lingers on close if data is present APR_SO_NONBLOCK -- Turns blocking on/off for socket When this option is enabled, use the APR_STATUS_IS_EAGAIN() macro to see if a send or receive function could not transfer data without blocking. APR_SO_REUSEADDR -- The rules used in validating addresses supplied to bind should allow reuse of local addresses. APR_SO_SNDBUF -- Set the SendBufferSize APR_SO_RCVBUF -- Set the ReceiveBufferSize
	on	Value for the option.

Definition at line 792 of file switch_apr.c.

Referenced by do_flush(), enable_local_rtcp_socket(), init_nat_monitor(), switch_rtp_clear_flag(), switch_rtp_set_flag(), switch_rtp_set_local_address(), switch_rtp_udptl_mode(), and switch_stun_lookup().

{
        return apr_socket_opt_set(sock, opt, on);
}

switch_status_t switch_socket_recv	(	switch_socket_t *	sock,
		char *	buf,
		switch_size_t *	len
	)

Read data from a network.

Parameters:

	sock	The socket to read the data from.
	buf	The buffer to store the data in.
	len	On entry, the number of bytes to receive; on exit, the number of bytes received.

Remarks:

 This functions acts like a blocking read by default.  To change 
 this behavior, use apr_socket_timeout_set() or the APR_SO_NONBLOCK
 socket option.
 The number of bytes actually received is stored in argument 3.

It is possible for both bytes to be received and an APR_EOF or other error to be returned.

 APR_EINTR is never returned.
 

Definition at line 751 of file switch_apr.c.

References SWITCH_STATUS_BREAK.

Referenced by unicast_thread_run().

{
        switch_status_t r;

        r = apr_socket_recv(sock, buf, len);

        if (r == 35 || r == 730035) {
                r = SWITCH_STATUS_BREAK;
        }

        return r;
}

switch_status_t switch_socket_recvfrom	(	switch_sockaddr_t *	from,
		switch_socket_t *	sock,
		int32_t	flags,
		char *	buf,
		size_t *	len
	)

Parameters:

	from	The apr_sockaddr_t to fill in the recipient info
	sock	The socket to use
	flags	The flags to use
	buf	The buffer to use
	len	The length of the available buffer

Definition at line 857 of file switch_apr.c.

References SWITCH_STATUS_BREAK, and SWITCH_STATUS_GENERR.

Referenced by do_flush(), read_rtcp_packet(), read_rtp_packet(), switch_nat_multicast_runtime(), switch_rtp_set_local_address(), and switch_stun_lookup().

{
        apr_status_t r = SWITCH_STATUS_GENERR;

        if (from && sock && (r = apr_socket_recvfrom(from, sock, flags, buf, len)) == APR_SUCCESS) {
                from->port = ntohs(from->sa.sin.sin_port);
                /* from->ipaddr_ptr = &(from->sa.sin.sin_addr);
                 * from->ipaddr_ptr = inet_ntoa(from->sa.sin.sin_addr);
                 */
        }

        if (r == 35 || r == 730035) {
                r = SWITCH_STATUS_BREAK;
        }

        return r;
}

switch_status_t switch_socket_send	(	switch_socket_t *	sock,
		const char *	buf,
		switch_size_t *	len
	)

Send data over a network.

Parameters:

	sock	The socket to send the data over.
	buf	The buffer which contains the data to be sent.
	len	On entry, the number of bytes to send; on exit, the number of bytes sent.

Remarks:

 This functions acts like a blocking write by default.  To change 
 this behavior, use apr_socket_timeout_set() or the APR_SO_NONBLOCK
 socket option.

It is possible for both bytes to be sent and an error to be returned.

 APR_EINTR is never returned.
 

Definition at line 708 of file switch_apr.c.

References SWITCH_STATUS_BREAK, SWITCH_STATUS_FALSE, SWITCH_STATUS_SUCCESS, and switch_yield.

{
        switch_status_t status = SWITCH_STATUS_SUCCESS;
        switch_size_t req = *len, wrote = 0, need = *len;
        int to_count = 0;

        while ((wrote < req && status == SWITCH_STATUS_SUCCESS) || (need == 0 && status == SWITCH_STATUS_BREAK) || status == 730035 || status == 35) {
                need = req - wrote;
                status = apr_socket_send(sock, buf + wrote, &need);
                if (status == SWITCH_STATUS_BREAK || status == 730035 || status == 35) {
                        if (++to_count > 60000) {
                                status = SWITCH_STATUS_FALSE;
                                break;
                        }
                        switch_yield(10000);
                } else {
                        to_count = 0;
                }
                wrote += need;
        }

        *len = wrote;
        return status;
}

switch_status_t switch_socket_send_nonblock	(	switch_socket_t *	sock,
		const char *	buf,
		switch_size_t *	len
	)

Definition at line 733 of file switch_apr.c.

References SWITCH_STATUS_GENERR.

{
        if (!sock || !buf || !len) {
                return SWITCH_STATUS_GENERR;
        }
        
        return apr_socket_send(sock, buf, len);
}

switch_status_t switch_socket_sendto	(	switch_socket_t *	sock,
		switch_sockaddr_t *	where,
		int32_t	flags,
		const char *	buf,
		switch_size_t *	len
	)

Parameters:

	sock	The socket to send from
	where	The apr_sockaddr_t describing where to send the data
	flags	The flags to use
	buf	The data to send
	len	The length of the data to send

Definition at line 742 of file switch_apr.c.

References SWITCH_STATUS_GENERR.

Referenced by do_stun_ping(), handle_ice(), ice_out(), ping_socket(), rtp_common_read(), rtp_common_write(), switch_ivr_park(), switch_rtp_set_local_address(), switch_rtp_write_frame(), switch_rtp_write_manual(), and switch_stun_lookup().

{
        if (!where || !buf || !len || !*len) {
                return SWITCH_STATUS_GENERR;
        }
        return apr_socket_sendto(sock, where, flags, buf, len);
}

switch_status_t switch_socket_shutdown	(	switch_socket_t *	sock,
		switch_shutdown_how_e	how
	)

Shutdown either reading, writing, or both sides of a socket.

Parameters:

	sock	The socket to close
	how	How to shutdown the socket. One of: SWITCH_SHUTDOWN_READ no longer allow read requests SWITCH_SHUTDOWN_WRITE no longer allow write requests SWITCH_SHUTDOWN_READWRITE no longer allow read or write requests

See also:

switch_shutdown_how_e

Remarks:

This does not actually close the socket descriptor, it just controls which calls are still valid on the socket.

Definition at line 678 of file switch_apr.c.

Referenced by switch_ivr_deactivate_unicast(), switch_rtp_kill_socket(), switch_rtp_udptl_mode(), and switch_stun_lookup().

{
        return apr_socket_shutdown(sock, (apr_shutdown_how_e) how);
}

switch_status_t switch_socket_timeout_set	(	switch_socket_t *	sock,
		switch_interval_time_t	t
	)

Setup socket timeout for the specified socket

Parameters:

	sock	The socket to set up.
	t	Value for the timeout. t > 0 -- read and write calls return APR_TIMEUP if specified time elapsess with no data read or written t == 0 -- read and write calls never block t < 0 -- read and write calls block

Definition at line 797 of file switch_apr.c.

{
        return apr_socket_timeout_set(sock, t);
}

---