NET_WebSocketSet.h

Go to the documentation of this file.

/*
 * POPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * NAME:        NET_WebSocketSet.h
 *
 * COMMENTS:
 *
 */

#ifndef __NET_WEBSOCKETSET_H__
#define __NET_WEBSOCKETSET_H__

#include "NET_API.h"

#include "NET_WebSocket.h"

#include <UT/UT_Array.h>
#include <UT/UT_ArrayStringMap.h>
#include <UT/UT_Map.h>
#include <UT/UT_SharedPtr.h>
#include <UT/UT_StringHolder.h>
#include <UT/UT_Url.h>

#include <chrono>

class NET_WebSocketSet;

/// The WebSocketSet is responsible for creating and managing one or more
/// client-side web socket connections.
///
/// The methods for sending data assume a "fire and forget" approach, with no
/// connection to data coming back through the sockets. As such, these methods
/// should be strictly non-blocking.
class NET_API NET_WebSocketSet
{
    friend class NET_WebSocketItem;

public:
    /// @brief Describes an event that has occured.
    class NET_API Event
    {
    public:
        enum Type
        {
            UNKNOWN,
            ERROR,
            CONNECTED,
            CONNECT_ERROR,
            DISCONNECTED,
            DISCONNECT_ERROR,
            MESSAGE_SENT,
            MESSAGE_SEND_ERROR,
            MESSAGE_RECEIVED,
            MESSAGE_RECEIVE_ERROR
        };

        Event() = default;
        Event(const Type& type, const UT_StringHolder& id, const NET_Time& t)
            : myId(id)
            , myType(type)
            , myUrl()
            , myTimestamp(t)
            , myError()
            , myMessage()
        {
        }

        friend std::ostream& operator<<(std::ostream& os, const Event ev)
        {
            // timestamp: TYPE(id) url message error

            os << ev.myTimestamp.toUTCString();
            os << ": ";

            switch (ev.myType)
            {
            case CONNECTED:
                os << "CONNECTED";
                break;
            case CONNECT_ERROR:
                os << "CONNECT ERROR";
                break;
            case DISCONNECTED:
                os << "DISCONNECTED";
                break;
            case DISCONNECT_ERROR:
                os << "DISCONNECT ERROR";
                break;
            case MESSAGE_SENT:
                os << "MESSAGE SENT";
                break;
            case MESSAGE_SEND_ERROR:
                os << "MESSAGE SEND ERROR";
                break;
            case MESSAGE_RECEIVED:
                os << "MESSAGE RECEIVED";
                break;
            case MESSAGE_RECEIVE_ERROR:
                os << "MESSAGE RECEIVE ERROR";
                break;
            default:
                os << "UNKNOWN";
                break;
            };

            os << "(" << ev.myId << ") " << ev.myUrl.toString();
            os << " Msg='" << ev.myMessage << "' Error='" << ev.myError << "'";

            return os;
        }

        /// @brief The type of event that occured.
        Type myType;

        /// @brief The url that the event originated from.
        UT_Url myUrl;
        /// @brief The connection id the event originated from.
        UT_StringHolder myId;
        /// @brief The time at which the event occured.
        NET_Time myTimestamp;
        /// @brief The error message if this is an error that occured.
        UT_StringHolder myError;
        /// @brief The message for the event. In the case of a message event
        /// this
        ///         is the read in event. In all other cases this describes the
        ///         details of the event in English.
        UT_StringHolder myMessage;
    };

    /// @brief Connect to a remote server.
    ///
    /// @param id The id of the connected websocket.
    /// @param url The url of the websocket.
    /// @param timeout The timeout to use before giving up on connecting.
    ///
    /// @return True if a connected websocket was produced.
    bool connect(
            const UT_StringRef& id,
            const UT_Url& url,
            const std::chrono::milliseconds& timeout);
    /// @brief Use this function to poll for new events if there are currently
    ///         no queued events.
    ///
    /// @param ev The object describing the event.
    /// @param timeout A timeout of 0 means only return an event if there is one
    //                  waiting. A timeout < 0 can be used to wait forever for
    //                  an event.
    ///
    /// @return True if this function is returning an event.
    bool getNextEvent(Event& ev, const std::chrono::milliseconds& timeout);
    /// @brief Close a specific connection based on the provided id. A
    ///         DISCONNECTED or DISCONNECT_ERROR will be generated.
    ///
    /// @param id The id to identify which connection to close.
    ///
    /// @return True if the connection was disconnected.
    bool disconnect(const UT_StringHolder& id);
    /// @brief Disconnect all connections this manager currently manages.
    void disconnectAll();
    /// @brief Send a message to a particular connection.
    /// This generates a MESSAGE_SENT or MESSAGE_SEND_ERROR.
    ///
    /// @param id The id of the connection to send the message too.
    /// @param wbuf The message to send.
    void sendMessage(const UT_StringHolder& id, const UT_StringHolder& message);

private:
    class NET_API Item : public NET_WebSocket
    {
    public:
        Item(NET_WebSocketSet& socket_set, const UT_StringHolder& id);

        void onEvent(const Event& ev) override;

        const UT_StringHolder& id() const { return myId; }

    private:
        NET_WebSocketSet& mySocketSet;
        UT_StringHolder myId;
    };

    /// @brief Callback for each an every websocket event. Currently this
    ///         translates and queues the event to be picked up later.
    ///
    /// @param ws The websocket the event happened on.
    /// @param ev The object describing the event.
    void queueEvent_(
            NET_WebSocketSet::Item* ws,
            const NET_WebSocket::Event& ev);
    /// @brief Disconnect the websocket using the websocket instance itself.
    /// This will lock the set.
    ///
    /// @param item The websocket instance to remove.
    ///
    /// @return True if the disconnect was a success.
    bool disconnectByWS_(const UT_SharedPtr<Item>& item);
    /// @brief Same as disconnectByWS except that this does not lock and as such
    /// is labelled as unsafe.
    ///
    /// @param item The websocket item instance to remove.
    ///
    /// @return True if the disconnect was a success.
    bool disconnectByWSUnsafe_(const UT_SharedPtr<Item>& item);

    UT_Lock myLock;
    /// @brief Maps the fd to the named ids.
    UT_Map<int, UT_StringHolder> myFDtoNamedIds;
    /// @brief Maps the named id to fds.
    UT_ArrayStringMap<UT_SharedPtr<Item>> myNamedIdToWebSockets;
    /// @brief Queue of events that occured.
    UT_Array<Event> myQueuedEvents;
};

#endif // __NET_WEBSOCKETSET_H__