vrpn_Auxiliary_Logger.h

// This is a base class interface that has been designed for use by
// scientific data-collection applications that make use of VRPN to
// connect to microscope imagers and tracking system for nanoscale
// science research at UNC.

// The idea of this interface is to enable a client GUI to start and
// stop logging of full-rate data on the server while receiving only
// a subset of the data during the experiment for preview; this keeps
// from overloading the network bandwidth with data and also keeps
// the client-side log files from filling up.  When new log file(s)
// are requested, the old log files are closed.

// Note that a particular implementation of the auxiliary logger server
// may need to know about a second connection (not the one it talks
// to its client over) in case that is where it is doing its logging.

#ifndef VRPN_AUXILIARY_LOGGER_H
#define VRPN_AUXILIARY_LOGGER_H
#include <string.h> // for NULL

#include "vrpn_BaseClass.h" // for vrpn_Callback_List, etc
#include "vrpn_Configure.h" // for VRPN_CALLBACK, VRPN_API
#include "vrpn_Connection.h"
#include "vrpn_Shared.h" // for timeval
#include "vrpn_Types.h"  // for vrpn_int32

class VRPN_API vrpn_Auxiliary_Logger : public vrpn_BaseClass {
public:
    vrpn_Auxiliary_Logger(const char *name, vrpn_Connection *c);

protected:
    // Handle registration of all message types we're going to deal with.
    virtual int register_types(void);
    vrpn_int32 request_logging_m_id; // ID of remote->server request message
    vrpn_int32 report_logging_m_id;  // ID of server->client response message
    vrpn_int32 request_logging_status_m_id; // ID of remote->server
                                            // status-request message

    // Pack a log description into the message whose type is passed
    // as the parameter (this is used to pack both the request and
    // report messages.
    bool pack_log_message_of_type(vrpn_int32 type,
                                  const char *local_in_logfile_name,
                                  const char *local_out_logfile_name,
                                  const char *remote_in_logfile_name,
                                  const char *remote_out_logfile_name);

    // Unpack a log description from a message into the four strings that
    // were passed in (this is used to unpack both the request and the
    // report messages).
    // NOTE: This routine will allocate space for the strings.  The caller
    // must delete [] this space when they are done with it to avoid
    // memory leaks.
    bool unpack_log_message_from_buffer(const char *buf, vrpn_int32 buflen,
                                        char **local_in_logfile_name,
                                        char **local_out_logfile_name,
                                        char **remote_in_logfile_name,
                                        char **remote_out_logfile_name);
};

// Virtual base server class for an auxiliiary logger.  An implementation must
// implement the specified message-handling functions and must call the base-
// class constructor to set up the calling of them.

class VRPN_API vrpn_Auxiliary_Logger_Server : public vrpn_Auxiliary_Logger {
public:
    vrpn_Auxiliary_Logger_Server(const char *name, vrpn_Connection *c);

    // Required for servers.
    virtual void mainloop(void) { server_mainloop(); }

protected:
    // Handle a logging-request message.  The request contains four file
    // names, two for local (to the Auxiliary server itself) and two for
    // remote (the far side of its connection to the server).  It must
    // also respond to the client with a message saying what logging has
    // been set up (using the send_logging_response function).  Logging is
    // turned off on a particular file by sending an empty-string name ("").
    // The in/out local/remote are with respect to the connection that the
    // logging is to occur on, which may or may not be the same one that the
    // client has connected to the object on using the constructor above.
    // Make sure to send a response saying what you did.
    virtual void
    handle_request_logging(const char *local_in_logfile_name,
                           const char *local_out_logfile_name,
                           const char *remote_in_logfile_name,
                           const char *remote_out_logfile_name) = 0;

    // Send a response to the client telling it what logging has been
    // established.
    bool send_report_logging(const char *local_in_logfile_name,
                             const char *local_out_logfile_name,
                             const char *remote_in_logfile_name,
                             const char *remote_out_logfile_name)
    {
        if (!d_connection) {
            return false;
        }
        return pack_log_message_of_type(
            report_logging_m_id, local_in_logfile_name, local_out_logfile_name,
            remote_in_logfile_name, remote_out_logfile_name);
    }

    // Handle dropped last connection on server object by turning off
    // logging.  The static method basically looks up the this
    // pointer and calls the virtual method.  A derived class should
    // re-implement the non-static method below if it doesn't want to drop all
    // logging or if it wants to do something else in addition.  The static
    // method basically just calls the non-static method.
    virtual void handle_dropped_last_connection(void);
    vrpn_int32 dropped_last_connection_m_id; // ID of message that all
                                             // connections dropped
    static int VRPN_CALLBACK
    static_handle_dropped_last_connection(void *userdata, vrpn_HANDLERPARAM p);

    // Static portion of handling (unpacking) the request_logging message.  It
    // then calls the non-static virtual method above.
    static int VRPN_CALLBACK
    static_handle_request_logging(void *userdata, vrpn_HANDLERPARAM p);

    // Handle request for logging status.
    virtual void handle_request_logging_status() = 0;
    static int VRPN_CALLBACK
    static_handle_request_logging_status(void *userdata, vrpn_HANDLERPARAM p);
};

// Generic server that will start auxiliary logs on the connection whose name
// is passed in (which can be the same as the name of the connection it is
// created on, but does not have to be).  The "local" in and out are with
// respect to the new connection that is made; the "remote" in and out are with
// respect to the named connection.  No logging is started in the constructor.

class VRPN_API vrpn_Auxiliary_Logger_Server_Generic
    : public vrpn_Auxiliary_Logger_Server {
public:
    // Does not start logging, just records what to log when it is started.
    vrpn_Auxiliary_Logger_Server_Generic(const char *logger_name,
                                         const char *connection_to_log,
                                         vrpn_Connection *c = NULL);
    ~vrpn_Auxiliary_Logger_Server_Generic();

    // Close an existing logging connection, then (if any of the file
    // names are non-empty) open a new logging connection to the
    // connection we are to log (even if this process already has a
    // connection to it) and then send back the report that we've started
    // logging if we are able.  If we cannot open it, then fill in all
    // blank names for the return report.
    virtual void handle_request_logging(const char *local_in_logfile_name,
                                        const char *local_out_logfile_name,
                                        const char *remote_in_logfile_name,
                                        const char *remote_out_logfile_name);

    virtual void handle_request_logging_status();

    // If we have an active logging connection, mainloop it and save all of its
    // pending messages in addition to handling the base-class functions.
    // Then call the parent class mainloop().
    virtual void mainloop(void)
    {
        if (d_logging_connection) {
            d_logging_connection->mainloop();
            d_logging_connection->save_log_so_far();
        }
        vrpn_Auxiliary_Logger_Server::mainloop();
    }

protected:
    char *d_connection_name;               // Name to connect to when logging.
    vrpn_Connection *d_logging_connection; // Connection to use for logging.
};

//-----------------------------------------------------------
//************** Client code uses the following *************

// Type of a client routine to request new logging and to handle a
// report of changed logging.  This callback is called when the
// logging server reports a new set of files, which should happen
// after each request is made.

typedef struct _vrpn_AUXLOGGERCB {
    struct timeval msg_time; // Timestamp of new logging
    const char *
        local_in_logfile_name; // Name of the incoming local log ("" if none).
    const char *local_out_logfile_name;
    const char *remote_in_logfile_name;
    const char *remote_out_logfile_name;
} vrpn_AUXLOGGERCB;

typedef void(VRPN_CALLBACK *vrpn_AUXLOGGERREPORTHANDLER)(
    void *userdata, const vrpn_AUXLOGGERCB info);

class VRPN_API vrpn_Auxiliary_Logger_Remote : public vrpn_Auxiliary_Logger {
public:
    vrpn_Auxiliary_Logger_Remote(const char *name, vrpn_Connection *c = NULL);

    // Send a request to the server asking it to log the following.  Each of
    // these is with respect to the connection that the auxiliary logger server
    // is handling, which may or may not be the one that it is connected to to
    // receive this message; it refers to the other side of the new connection
    // that the server establishes to do its logging.  Passing a NULL or empty
    // string ("") to any of the entries disables that log.
    // WARNING: If the server is set to connect to its own connection and log
    // it, then you must explicitly request a set of empty log files to stop
    // it logging the last time because otherwise it never gets the message
    // that it dropped the last connection and will continue logging after the
    // object is destroyed.
    bool send_logging_request(const char *local_in_logfile_name,
                              const char *local_out_logfile_name = "",
                              const char *remote_in_logfile_name = "",
                              const char *remote_out_logfile_name = "")
    {
        if (!d_connection) {
            return false;
        }
        return pack_log_message_of_type(
            request_logging_m_id, local_in_logfile_name, local_out_logfile_name,
            remote_in_logfile_name, remote_out_logfile_name);
    }

    bool send_logging_status_request()
    {
        if (!d_connection) {
            return false;
        }
        return pack_log_message_of_type(request_logging_status_m_id, NULL, NULL,
                                        NULL, NULL);
    }

    // Register/unregister a callback handler for the logging response.
    virtual int register_report_handler(void *userdata,
                                        vrpn_AUXLOGGERREPORTHANDLER handler)
    {
        return d_callback_list.register_handler(userdata, handler);
    };
    virtual int unregister_report_handler(void *userdata,
                                          vrpn_AUXLOGGERREPORTHANDLER handler)
    {
        return d_callback_list.unregister_handler(userdata, handler);
    }

    // This routine calls the mainloop of the connection it's on
    virtual void mainloop(void);

protected:
    // Static handler for the logging report message.
    // Use the base-class unpack method to convert the data into strings.
    vrpn_Callback_List<vrpn_AUXLOGGERCB> d_callback_list;

    static int VRPN_CALLBACK
    handle_report_message(void *userdata, vrpn_HANDLERPARAM p);
};

#endif