src/lwes_net_functions.h

   1 /*======================================================================*
   2  * Copyright (C) 2008 Light Weight Event System                         *
   3  * All rights reserved.                                                 *
   4  *                                                                      *
   5  * This program is free software; you can redistribute it and/or modify *
   6  * it under the terms of the GNU General Public License as published by *
   7  * the Free Software Foundation; either version 2 of the License, or    *
   8  * (at your option) any later version.                                  *
   9  *                                                                      *
  10  * This program is distributed in the hope that it will be useful,      *
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of       *
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the        *
  13  * GNU General Public License for more details.                         *
  14  *                                                                      *
  15  * You should have received a copy of the GNU General Public License    *
  16  * along with this program; if not, write to the Free Software          *
  17  * Foundation, Inc., 51 Franklin Street, Fifth Floor,                   *
  18  * Boston, MA 02110-1301 USA.                                           *
  19  *======================================================================*/
  20 #ifndef __LWES_NET_FUNCTIONS_H
  21 #define __LWES_NET_FUNCTIONS_H
  22
  23 #include <stdio.h>
  24 #include <stdlib.h>
  25 #include <ctype.h>
  26 #include <errno.h>
  27 #include <sys/types.h>
  28 #include <sys/time.h>
  29 #include <sys/socket.h>
  30 #include <netinet/in.h>
  31 #include <arpa/inet.h>
  32 #include <unistd.h>
  33
  34 #include "lwes_types.h"
  35
  36 #ifdef __cplusplus
  37 extern "C" {
  38 #endif
  39
  40 /*! \file lwes_net_functions.h
  41  *  \brief Functions for dealing with multicast channels
  42  */
  43
  44 /*! \struct lwes_net_connection lwes_net_functions.h
  45  *  \brief   IP Multicast Channel object
  46  */
  47 struct lwes_net_connection
  48 {
  49   /*! low level socket descriptor */
  50   int socketfd;
  51
  52   /*! inet address for the multicast channel */
  53   struct sockaddr_in mcast_addr;
  54
  55   /*! mcast struct */
  56   struct ip_mreq     mreq;
  57
  58   /*! inet address for the sender of this packet */
  59   struct sockaddr_in sender_ip_addr;
  60
  61   /*! used to stored the size of the above structure */
  62   socklen_t sender_ip_socket_size;
  63
  64   /*! boolean, will be TRUE if we have joined a multicast group.
  65       we only join a multicast group if we are receiving packets */
  66   int hasJoined;
  67 };
  68
  69 /*! \brief Open a multicast channel
  70  *
  71  *  \param[in] conn the multicast channel object to hole this connection
  72  *  \param[in] address the multicast IP address of the channel to connect to
  73  *  \param[in] iface the IP address of the network interface this channel shoul
  74  *                   be connected to
  75  *  \param[in] port the multicast port of the channel to connect to
  76  *
  77  *  \return 0 on success, a negative number on error
  78  */
  79 int
  80 lwes_net_open
  81   (struct lwes_net_connection *conn,
  82    const char *address,
  83    const char *iface,
  84    int port);
  85
  86 /*! \brief Close a multicast channel
  87  *
  88  *  \param[in] conn the multicast channel object containing the
  89  *                  connection to close
  90  *
  91  *  \return 0 on success, a negative number on error
  92  */
  93 int
  94 lwes_net_close
  95   (struct lwes_net_connection *conn);
  96
  97 /*! \brief Get the current Time-To-Live on a multicast channel
  98  *
  99  *  \param[in] conn the multicast channel to get the ttl for
 100  *
 101  *  \returns the current ttl value on success, a negative number on error
 102  */
 103 int
 104 lwes_net_get_ttl
 105   (struct lwes_net_connection *conn);
 106
 107 /*! \brief Set a new Time-To-Live on a multicast channel
 108  *
 109  *  \param[in] conn the multicast channel to get the ttl for
 110  *  \param[in] new_ttl the new ttl to set for outgoing packets
 111  *
 112  *  \return 0 on success, a negative number on error
 113  */
 114 int
 115 lwes_net_set_ttl
 116   (struct lwes_net_connection *conn, int new_ttl);
 117
 118 /*! \brief Get the socket file descriptor for the multicast channel
 119  *
 120  *  \param[in] conn the multicast channel to get the socket file descriptor for
 121  *
 122  *  \return the file descriptor on success, a negative number on error
 123  */
 124 int
 125 lwes_net_get_sock_fd
 126   (struct lwes_net_connection *conn);
 127
 128 /*! \brief Send bytes to the multicast channel
 129  *
 130  *  \param[in] conn the multicast channel to send bytes to
 131  *  \param[in] bytes an array of bytes to send out on the channel
 132  *  \param[in] len the number of bytes from bytes to send out on the channel
 133  *
 134  *  \return the number of bytes sent on success, a negative number on failure
 135  */
 136 int
 137 lwes_net_send_bytes
 138   (struct lwes_net_connection *conn,
 139    LWES_BYTE_P bytes,
 140    size_t len);
 141
 142 /*! \brief Send bytes to a different multicast channel
 143  *
 144  *  This can be used to send bytes out over an alternate channel, this will
 145  *  result in the creation and destruction of a struct lwes_net_connection
 146  *  internally.
 147  *
 148  *  \param[in] conn the multicast channel to ignore since it's not used in this
 149  *                  call
 150  *  \param[in] address the multicast IP address of the channel to connect to
 151  *  \param[in] iface the IP address of the network interface this channel shoul
 152  *                   be connected to
 153  *  \param[in] port the multicast port of the channel to connect to
 154  *  \param[in] bytes the bytes to send to the alternate channel
 155  *  \param[in] len the number of bytes to send to the alternate channel
 156  *
 157  *  \return the number of bytes sent on success, a negative number on failure
 158  */
 159 int
 160 lwes_net_sendto_bytes
 161   (struct lwes_net_connection *conn,
 162    char *address,
 163    char *iface,
 164    int port,
 165    LWES_BYTE_P bytes,
 166    size_t len);
 167
 168 /*! \brief Bind to the multicast channel
 169  *
 170  *  Used to actually bind to a channel, this should only be called if one
 171  *  plans to receive bytes from the channel
 172  *
 173  *  \param[in] conn the multicast channel to bind to
 174  *
 175  *  \return 0 on success, a negative number on failure
 176  */
 177 int
 178 lwes_net_recv_bind
 179   (struct lwes_net_connection *conn);
 180
 181 /*! \brief Receive bytes from the multicast channel in blocking mode
 182  *
 183  *  This calls lwes_net_recv_bind internally.
 184  *
 185  *  \param[in] conn the multicast channel to receive bytes from
 186  *  \param[out] bytes the byte array to fill out
 187  *  \param[in] len the size of the byte array to fill out
 188  *
 189  *  \return the number of bytes received on success, a negative number on
 190  *          failure
 191  */
 192 int
 193 lwes_net_recv_bytes
 194   (struct lwes_net_connection *conn,
 195    LWES_BYTE_P bytes,
 196    size_t len);
 197
 198 /*! \brief Receive bytes from the multicast channel with a timeout
 199  *
 200  *  This calls lwes_net_recv_bind internally.
 201  *
 202  *  \param[in] conn the multicast channel to receive bytes from
 203  *  \param[out] bytes the byte array to fill out
 204  *  \param[in] len the size of the byte array to fill out
 205  *  \param[in] timeout_ms the maximum time to block on this call
 206  *
 207  *  \return the number of bytes received on success, a negative number on
 208  *          failure
 209  */
 210 int
 211 lwes_net_recv_bytes_by
 212   (struct lwes_net_connection *conn,
 213    LWES_BYTE_P bytes,
 214    size_t len,
 215    unsigned int timeout_ms);
 216
 217 #ifdef __cplusplus
 218 }
 219 #endif
 220
 221 #endif /* __NET_FUNCTIONS_H */