vos/corelibs/servicediscovery/servicedirectory.hh

Go to the documentation of this file.

/*  $Id: servicedirectory.hh,v 1.20 2003/07/05 04:07:16 tetron Exp $

    Copyright (C) 2002 Peter Amstutz <tetron@interreality.org>

    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Lesser General Public
    License as published by the Free Software Foundation; either
    version 2 of the License, or (at your option) any later version.

    This library is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    Lesser General Public License for more details.

    You should have received a copy of the GNU Lesser General Public
    License along with this library; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA

*/

#ifndef _SERVICEDIRECTORY_HH_
#define _SERVICEDIRECTORY_HH_

#include <string>
#include <set>
#include <deque>
#include <map>

/** Library for Service Discovery */
namespace LSD {

struct Service
{
public:
    std::set<std::string> types;
    std::string title;
    std::string description;
    std::string url;
    Service() {}
    Service(const std::set<std::string>& ty, const std::string& ti, const
std::string& d, const std::string& u) :
        types(ty), title(ti), description(d), url(u) {}
};



class ServiceAdvertismentListener
{
public:
    virtual ~ServiceAdvertismentListener() { }
    virtual void notifyNewService(int id, const Service& s) = 0;
};

/** This class represents a service directory. Service directories can query and
 *  advertise services which are registered locally, or remotely, via UDP
 *  broadcast or point-to-point TCP messages.
 *  A service is identified by human readable title and description, a list
 *  of type strings, and a URL.
 *  @todo add optional relaying of all local traffic to remote
 *  tcp relays.
 */
class ServiceDirectory
{
private:
    std::set<Service*> services;
    int udp_fd;                                 // incoming and outgoing broadcasts
    std::map< std::pair<char*, int>, int > tcp_relays;    // outgoing relays
    int tcp_fd;                                 // listening
    std::deque<int> incoming_tcp_fds;                // incoming tpc sockets
    bool relay_tcp_local;                       // if true, relay incoming messages from the tcp sockets to the broadcast
    bool relay_udp_remote;                       // if true, relay incoming messages from the udp socket to the remote relays
    bool relay_tcp_remote;                       // if true, relay incoming messages from the incoming tcp sockets to the remote relay tcp sockets
    int udp_port;

public:
    struct Query
    {
        std::string typepattern;
        std::string titlepattern;
        std::string descpattern;
        std::string urlpattern;
        ServiceAdvertismentListener* listener;
    };

private:
    std::map<int, Query> queries;


public:

    /** @name Options you can pass to the constructor */
    //@{
    static short LISTEN_BCAST;          ///< Listen on local subnet UDP broadcast
    static short LISTEN_TCP;            ///< Listen on TCP port 4229
    static short RELAY_TCP_TO_BCAST;    ///< Relay from TCP ports to local broadcast
    static short RELAY_BCAST_TO_TCP;    ///< Relay from local broadcast to remote TCP relay points. @see addRelay
    static short RELAY_TCP_TO_REMOTE;    ///< Relay from incoming TCP ports to remote relay points (see addRelay)
    //@}

public:
    /** Constructor.
        @param options  Mask of options: see above. Options may be combined with
        |. The defaults may be negated with ^ (e.g. ^ServiceDirectory::LISTEN_BCAST)
    */
    ServiceDirectory(short options);

    /** Constructor. Uses default options * LISTEN_BCAST|RELAY_TCP_TO_BCAST|RELAY_BCAST_TO_TCP */
    ServiceDirectory();

    /** Destructor: all open sockets are shut down. */
    virtual ~ServiceDirectory();

    /** Start a query on both this directory and remote directories for services which
     *  match the given patterns. The listener is notified when a matching
     *  service is found.
     *  If any remote relays have been added, the query will also be sent to
     *  each one (see addRelay())
     *  @return a unique identifier for this query
     */
    virtual int query(const std::string& typepattern,
              const std::string& titlepattern,
              const std::string& descpattern,
              const std::string& urlpattern,
              ServiceAdvertismentListener* cb);

    /** End query with identifier q */
    virtual void endQuery(int q);

    /** Add service to directory */
    virtual void addService(Service* s);

    /** Remove service from directory */
    virtual void removeService(Service* s);

    /** Check UDP and TCP sockets (via a call to select), and handle
     * incoming queries and advertisements from remote directories.
     * This method must be called periodically in order to maintain an
     * active directory.
     * @param timeout   Timeout on select call, in seconds. Omit the parameter
                        or use -1 to block until a socket has data. Use 0 to
                        return immediately.
     */
    virtual void handleIncoming(float timeout = -1);



    /** Also relay queries via TCP to service directory running at the
     *  given host and port.
     *  Use with listenTCP() to span networks.
     */
    virtual void addRelay(char* hostname, int port = 4229);

    /** Don't relay queries to the specified directory */
    virtual void removeRelay(char* hostname, int port = 4229);

    /** Get UDP socket file descriptor */
    virtual int getUDPfd() { return udp_fd; }

    /** Get TCP socket file descriptor (listening) */
    virtual int getTCPfd() { return tcp_fd; }

    /** Get outgoing tcp remote relay file descriptors */
    virtual std::deque<int> getRelayFds();

    /** Get incoming tcp file descriptors */
    virtual std::deque<int> getIncomingTCPFds() ;

    /** Listen on a TCP port for messages, which will be responded to in
     * handleIncoming().
     *  @param port     Port to listen on. If -1, then any open TCP socket will
     *   be closed.
     *
     *  Call relayIncomingTCP() to cause handleIncoming() to also relay
     *  messages to local broadcast.
     *  Use with addRelay() to span networks with a symetrical set-up on
     *  the other end.
     *  This feature can also be used as a simple way to enable multiple
     *  services to share a host's service directory.
     *
     *  If you passed ServiceDirectory::LISTEN_TCP to the constructor,
     *  then calling this is  unnecessary.
     *
     *  You can only listen on one TCP port.
     */
    virtual void listenTCP(int port = 4229);

    /** Listen on a UDP port for messages, which will be responded to in
     * handleIncoming().
     *  @param port     Port to listen on. If -1, then any open TCP socket will
     *   be closed. You want to use the default, 4230, unless the other
     *   service directories on the socal net that you want to talk to are
     *   using some other port for recieving udp broadcast messages.
     *
     * If you pass ServiceDirectory::LISTEN_BCAST to the constructor,
     * (the default argument) then calling this is unnecessary.
     *
     * You can only listen on one UDP port.
     */
    virtual void listenUDP(int port = 4230);

    /** Cause handleIncoming() to also relay incomming TCP messages broadcast to
     *  local network (or stop relaying if argument is false).
     *
     *  (Only useful if listenTCP() has been called or
     *  ServiceDirectory::LISTEN_TCP was passed to the constructor.
     *  Calling this is the same as passing
     *  ServiceDirectory::RELAY_TCP_TO_BCAST|ServiceDirectory::LISTEN_TCP
     *   to the constructor.)
     */
    virtual void relayIncomingTCP(bool v = true) {
        relay_tcp_local = v;
    }
};

}; // namespace

#endif

---