netlib.h

Go to the documentation of this file.

/*
 * netlib.h
 *
 * Copyright (C) 2007,2009,2010  Thomas A. Vaughan
 * All rights reserved.
 *
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *     * Redistributions of source code must retain the above copyright
 *       notice, this list of conditions and the following disclaimer.
 *     * Redistributions in binary form must reproduce the above copyright
 *       notice, this list of conditions and the following disclaimer in the
 *       documentation and/or other materials provided with the distribution.
 *     * Neither the name of the <organization> nor the
 *       names of its contributors may be used to endorse or promote products
 *       derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THOMAS A. VAUGHAN ''AS IS'' AND ANY
 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL THOMAS A. VAUGHAN BE LIABLE FOR ANY
 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 *
 * Networking library.  This is a layer on top of BSD sockets that handles
 * some threading etc.  Somewhat tailored to my specific applications.
 */

#ifndef WAVEPACKET_NETLIB_H__
#define WAVEPACKET_NETLIB_H__


// includes --------------------------------------------------------------------
#include "message-buffer.h"
#include "wavesock.h"


namespace netlib {


// networking typedefs ---------------------------------------------------------

////////////////////////////////////////////////////////////////////////////////
///
/// \ingroup networking
/// \defgroup netlib Networking API
///
///     This is a very basic networking API layer.  You can create connections
///     (using the various constructors) and get back a connection ID.  Then
///     you can read/write to the connection based on the ID.
///
///     You can write to the connection any time using the connection ID.
///
///     <b>The getNextMessage() API is the core message pump.</b>
///     The application should repeatedly call this so that messages get sent
///     in and out.
///
///     \b WARNING: this library is NOT threadsafe!  You should handle any
///     synchronization issues at a higher layer.
///
////////////////////////////////////////////////////////////////////////////////
/*@{*/

/// connection ID type.  Will never be null for a valid connection.
typedef dword_t conn_id_t;


/// the type of connection
enum eConnectionType {
        eType_TCP               = 0x0001,       ///< standard tcp/ip connection
        eType_SecureTCP         = 0x0002,       ///< ssl connection

        eType_UDPLocal          = 0x0010,       ///< can send/receive UDP datagrams
        eType_UDPRemote         = 0x0020,       ///< our record of remote UDP socket
        eType_UDPBroadcast      = 0x0040,       ///< can broadcast UDP datagrams

        eType_TCPListener       = 0x0100,       ///< local tcp listening socket

        // must be last!
        eType_Invalid           = 0
};



struct connection_info_t {
        // constructor, manipulator
        connection_info_t(void) throw() { this->clear(); }
        void clear(void) throw() {
                        type = eType_Invalid;
                        address.clear();
                        port = 0;
                }
        bool is_valid(void) const throw() {
                        return (eType_Invalid != type);
                }
        void dump(IN const char * title) const throw();

        // data fields
        eConnectionType         type;
        address_t               address;
        int                     port;
};



/// An envelope describes from where and how a remote message arrived
struct envelope_t {
        // constructor, manipulators
        envelope_t(void) throw() { this->clear(); }
        void clear(void) throw() {
                        fromConnId = 0;
                        type = eType_Invalid;
                        address.clear();
                }
        bool is_empty(void) const throw() {
                        return (eType_Invalid == type);
                }
        bool isValid(void) const throw() {
                        if (eType_Invalid == type)
                                return false;
                        if (fromConnId)
                                return true;    // assume so...
                        return address.isValid();
                }

        // data fields
        conn_id_t               fromConnId;     /// source connection ID
        eConnectionType         type;
        address_t               address;
};




////////////////////////////////////////////////////////////////////////////////
//
//      public API
//
////////////////////////////////////////////////////////////////////////////////
/// \ingroup netlib
/*@{*/


/// return the hostname (or IP in string form!)
std::string getServerFromIP(IN const ip_addr_t& ip);


/// create a listener (if clients connect, you'll see their messages show up)
conn_id_t createTcpListener(IN const address_t& address,
                                IN int maxBacklog);

/// create a connection to a remote peer (connection ID is returned)
conn_id_t createTcpConnection(IN const address_t& address);


/// create a local UDP connection for sending/receiving datagrams.
/// This connection will receive datagrams sent to this local port from any
///     remote location (including broadcast packets).
/// You have to specify the full local address.  This is important for
///     machines with multiple interfaces, and even for a machine with a
///     single interface, you need to specify the physical interface vs.
///     a local host loopback (127.0.0.1).
/// To send UDP datagrams from this connection, create a remote UDP
///     connection using createUdpRemote() and use this connection as the
///     localUdp connection.
/// To broadcast UDP datagrams, you won't use this connection at all.  Instead,
///     create a broadcast UDP datagram connection using createUdpBroadcast().
conn_id_t createUdpLocal(IN const address_t& localUdp);

/// create a logical connection to represent a remote UDP sender/receiver
///  - caller must specify the local UDP connection that will communicate
/// this is used for sending to remote UDP listeners
conn_id_t createUdpRemote(IN conn_id_t localUdp,
                                IN const address_t& address);

/// create a local UDP sending point for datagram broadcasts to a specific port.
/// Caller must specify the broadcast address, such as 192.168.0.255 
conn_id_t createUdpBroadcast(IN const address_t& broadcastAddress);


/// asynchronously send data to a particular connection
/// -  conn_id specifies the (remote) receiver
/// -  queued messages are actually sent via getNextMessage() calls
bool enqueueMessage(IN conn_id_t connId,
                                IN smart_ptr<MessageBuffer>& message);


/// get next message from all open connections (empty if no messages waiting)
///  - this is the main message pump so applications should keep calling it
bool getNextMessage(IN long wait_microseconds,
                                OUT netlib::envelope_t& envelope,
                                OUT smart_ptr<MessageBuffer>& buffer);


/// is this a valid connection?
bool isValidConnection(IN conn_id_t conn_id);


/// given a connection, retrieve information about it
bool getConnectionInfo(IN conn_id_t conn_id,
                                OUT connection_info_t& info);

/// terminate a particular connection
void closeConnection(IN conn_id_t conn_id);

/// for debugging
void dumpMessage(IO std::ostream& stream,
                                IN const char * title,
                                IN const envelope_t& envelope,
                                IN const MessageBuffer * buffer);

/// info only
void dumpStats(void);


};      // netlib namespace



#endif  // WAVEPACKET_NETLIB_H__