Network Routines
[Brought To You By APR]

Modules
group	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_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)
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_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_recvfrom (switch_sockaddr_t *from, switch_socket_t *sock, int32_t flags, char *buf, size_t *len)
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)

---

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

#define SWITCH_SO_DEBUG   4

#define SWITCH_SO_DISCONNECTED   256

#define SWITCH_SO_KEEPALIVE   2

#define SWITCH_SO_LINGER   1

#define SWITCH_SO_NONBLOCK   8

#define SWITCH_SO_RCVBUF   128

#define SWITCH_SO_REUSEADDR   16

#define SWITCH_SO_SNDBUF   64

#define SWITCH_UNSPEC   0

Let the system decide which address family to use

---

Typedef Documentation

typedef struct apr_sockaddr_t switch_sockaddr_t

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

typedef struct apr_socket_t switch_socket_t

A structure to represent sockets

---

Enumeration Type Documentation

enum switch_shutdown_how_e

Enumeration values: 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_READ, SWITCH_SHUTDOWN_WRITE, SWITCH_SHUTDOWN_READWRITE } switch_shutdown_how_e;

---

Function Documentation

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

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

Here is the call graph for this function:

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) { return apr_mcast_join(sock, join, iface, source); }

int32_t switch_sockaddr_get_family (  switch_sockaddr_t *  sa  )

{ return sa->family; }

uint16_t switch_sockaddr_get_port (  switch_sockaddr_t *  sa  )

{ 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. { return apr_sockaddr_info_get(sa, hostname, family, port, flags, pool); }

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

{ 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. { return apr_socket_accept(new_sock, sock, pool); }

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. { 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 { 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. { 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 { 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. { 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. { 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. { return apr_socket_recv(sock, buf, len); }

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 { apr_status_t r; if ((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 = 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. { 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) { need = req - wrote; status = apr_socket_send(sock, buf + wrote, &need); if (status == SWITCH_STATUS_BREAK || status == 730035) { if (++to_count > 10000) { status = SWITCH_STATUS_FALSE; break; } switch_yield(1000); } else { to_count = 0; } wrote += need; } *len = wrote; return status; }

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 { 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. { 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 { return apr_socket_timeout_set(sock, t); }

---