vrpn_FileConnection.h

#ifndef VRPN_FILE_CONNECTION_H
#define VRPN_FILE_CONNECTION_H

// {{{ vrpn_File_Connection
//
// Tom Hudson, June 1998

// This class *reads* a file written out by vrpn_Connection's logging hooks.

// The interface exactly matches that of vrpn_Connection.  To do things that
// are meaningful on log replay but not on live networks, create a
// vrpn_File_Controller and pass your vrpn_File_Connection to its constructor,
// or just ask the Connection for its file connection pointer and do the
// operations directly on the FileConnection if the pointer is non-NULL.

// Logfiles are recorded as *sent*, not as translated by the receiver,
// so we still need to have all the correct names for senders and types
// registered.

// September 1998:  by default preloads the entire log file on startup.
// This causes a delay (nontrivial for large logs) but should help smooth
// playback.
// }}}

#include <stdio.h> // for NULL, FILE

#include "vrpn_Configure.h"  // for VRPN_API, VRPN_CALLBACK
#include "vrpn_Connection.h" // for vrpn_LOGLIST (ptr only), etc
#include "vrpn_Shared.h"     // for timeval
#include "vrpn_Types.h"      // for vrpn_float32, vrpn_int32, etc

struct timeval;

// Global variable used to indicate whether File Connections should
// pre-load all of their records into memory when opened.  This is the
// default behavior, but fails on very large files that eat up all
// of the memory.  This defaults to "true".  User code should set this
// to "false" before calling vrpn_get_connection_by_name() or creating
// a new vrpn_File_Connection object if it wants that file connection
// to not preload.  The value is only checked at connection creation time;
// the connection behaves consistently once created.  This operation is
// useful for applications that load large data files and don't want to
// wait for them to pre-load.

extern VRPN_API bool vrpn_FILE_CONNECTIONS_SHOULD_PRELOAD;

// Global variable used to indicate whether File Connections should
// keep already-read messages stored in memory.  If not, then we have
// to re-load the file starting at the beginning on rewind.  This
// defaults to "true".  User code should set this
// to "false" before calling vrpn_get_connection_by_name() or creating
// a new vrpn_File_Connection object if it wants that file connection
// to not preload.  The value is only checked at connection creation time;
// the connection behaves consistently once created.  This operation is
// useful for applications that read through large data files and
// don't have enough memory to keep them in memory at once, or for applications
// that read through only once and have no need to go back and check.

extern VRPN_API bool vrpn_FILE_CONNECTIONS_SHOULD_ACCUMULATE;

// Global variable used to indicate whether File Connections should
// play through all system messages and get to the first user message
// when opened or reset to the beginning.  This defaults to "true".
// User code should set this
// to "false" before calling vrpn_get_connection_by_name() or creating
// a new vrpn_File_Connection object if it wants that file connection
// to not preload.  The value is only checked at connection creation time;
// the connection behaves consistently once created.  Leaving this true
// can help with offsets in time that happen at the beginning of files.

extern VRPN_API bool vrpn_FILE_CONNECTIONS_SHOULD_SKIP_TO_USER_MESSAGES;

class VRPN_API vrpn_File_Connection : public vrpn_Connection {
public:
    vrpn_File_Connection(const char *station_name,
                         const char *local_in_logfile_name = NULL,
                         const char *local_out_logfile_name = NULL);
    virtual ~vrpn_File_Connection(void);

    virtual int mainloop(const timeval *timeout = NULL);

    // returns the elapsed time in the file
    virtual int time_since_connection_open(timeval *elapsed_time);

    // returns the current time in the file since the epoch (UTC time).
    virtual timeval get_time() { return d_time; }

    virtual vrpn_File_Connection *get_File_Connection(void);

    // Pretend to send pending report, really just clear the buffer.
    virtual int send_pending_reports(void);

    // {{{ fileconnections-specific methods (playback control)
public:
    // XXX the following should not be public if we want vrpn_File_Connection
    //     to have the same interface as vrpn_Connection
    //
    //     If so handler functions for messages for these operations
    //     should be made, and functions added to vrpn_File_Controller which
    //     generate the messages.  This seemed like it would be messy
    //     since most of these functions have return values

    // rate of 0.0 is paused, 1.0 is normal speed
    void set_replay_rate(vrpn_float32 rate)
    {
        d_filetime_accum.set_replay_rate(rate);
    }

    vrpn_float32 get_replay_rate() { return d_filetime_accum.replay_rate(); }

    // resets to the beginning of the file
    // returns 0 on success
    int reset(void);

    // returns 1 if we're at the end of file
    int eof();

    // end_time for play_to_time() is an elapsed time
    // returns -1 on error or EOF, 0 on success
    int play_to_time(vrpn_float64 end_time);
    int play_to_time(timeval end_time);

    // end_filetime is an absolute time, corresponding to the
    // timestamps of the entries in the file,
    // returns -1 on error or EOF, 0 on success
    int play_to_filetime(const timeval end_filetime);

    // plays the next entry, returns -1 or error or EOF, 0 otherwise
    int playone();

    // plays at most one entry, but won't play past end_filetime
    // returns 0 on success, 1 if at end_filetime, -1 on error or EOF
    int playone_to_filetime(timeval end_filetime);

    // returns the elapsed time of the file
    timeval get_length();
    double get_length_secs();

    // returns the timestamp of the earliest in time user message
    timeval get_lowest_user_timestamp();

    // returns the timestamp of the greatest-in-time user message
    timeval get_highest_user_timestamp();

    // returns the name of the file
    const char *get_filename();

    // jump_to_time sets the current position to the given elapsed time
    // return 1 if we got to the specified time and 0 if we didn't
    int jump_to_time(vrpn_float64 newtime);
    int jump_to_time(timeval newtime);

    // jump_to_filetime sets the current position to the given absolute time
    // return 1 if we got to the specified time and 0 if we didn't
    int jump_to_filetime(timeval absolute_time);

    // Limits the number of messages played out on any one call to mainloop.
    // 0 => no limit.
    // Used to stop continuous callback-handling when messages arrive
    // at a very high rate (such as from a vrpn_Imager) or to make sure
    // that we are able to pause after each frame in frame-by-frame
    // playback for tracking analysis programs.
    void limit_messages_played_back(vrpn_uint32 max_playback)
    {
        Jane_stop_this_crazy_thing(max_playback);
    };

    // }}}
    // {{{ tokens for VRPN control messages (data members)
protected:
    vrpn_int32 d_controllerId;

    vrpn_int32 d_set_replay_rate_type;
    vrpn_int32 d_reset_type;
    vrpn_int32 d_play_to_time_type;
    // long d_jump_to_time_type;

    // }}}
    // {{{ time-keeping
protected:
    timeval d_last_told;  // Last time we printed error about no open file.
    timeval d_time;       // current time in file
    timeval d_start_time; // time of first record in file
    timeval d_earliest_user_time; // time of first user message
    vrpn_bool d_earliest_user_time_valid;
    timeval d_highest_user_time; // time of last user message
    vrpn_bool d_highest_user_time_valid;

    // finds the timestamps of the earliest and highest-time user messages
    void find_superlative_user_times();

    // these are to be used internally when jumping around in the
    // stream (e.g., for finding the earliest and latest timed
    // user messages).  They assume
    //   1) that only functions such as advance_currentLogEntry,
    //      read_entry and manual traversal of d_logHead/d_logTail
    //      will be used.
    // the functions return false if they don't save or restore the bookmark
    class VRPN_API vrpn_FileBookmark {
    public:
        vrpn_FileBookmark();
        ~vrpn_FileBookmark();
        bool valid;
        timeval oldTime;
        long int file_pos;                   // ftell result
        vrpn_LOGLIST *oldCurrentLogEntryPtr; // just a pointer, useful for accum
                                             // or preload
        vrpn_LOGLIST *oldCurrentLogEntryCopy; // a deep copy, useful for
                                              // no-accum, no-preload
    };
    bool store_stream_bookmark();
    bool return_to_bookmark();
    vrpn_FileBookmark d_bookmark;

    // wallclock time at the (beginning of the) last call
    // to mainloop that played back an event
    timeval d_last_time; // XXX remove

    class VRPN_API FileTime_Accumulator {
        // accumulates the amount of time that we will advance
        // filetime by when we next play back messages.
        timeval d_filetime_accum_since_last_playback;

        // wallclock time when d_filetime_accum_since_last_playback
        // was last updated
        timeval d_time_of_last_accum;

        // scale factor between stream time and wallclock time
        vrpn_float32 d_replay_rate;

    public:
        FileTime_Accumulator();

        // return accumulated time since last reset
        const timeval &accumulated(void)
        {
            return d_filetime_accum_since_last_playback;
        }

        // return last time accumulate_to was called
        const timeval &time_of_last_accum(void) { return d_time_of_last_accum; }

        vrpn_float32 replay_rate(void) { return d_replay_rate; }

        // add (d_replay_rate * (now_time - d_time_of_last_accum))
        // to d_filetime_accum_since_last_playback
        // then set d_time_of_last_accum to now_time
        void accumulate_to(const timeval &now_time);

        // if current rate is non-zero, then time is accumulated
        // before d_replay_rate is set to new_rate
        void set_replay_rate(vrpn_float32 new_rate);

        // set d_time_of_last_accum to now_time
        // and set d_filetime_accum_since_last_playback to zero
        void reset_at_time(const timeval &now_time);
    };
    FileTime_Accumulator d_filetime_accum;

    // }}}
    // {{{ actual mechanics of the logfile
protected:
    char *d_fileName;
    FILE *d_file;

    void play_to_user_message();

    // helper function for mainloop()
    int need_to_play(timeval filetime);

    // checks the cookie at
    // the head of the log file;
    //  exit on error!
    virtual int read_cookie(void);

    virtual int read_entry(void); // appends entry to d_logTail
                                  // returns 0 on success, 1 on EOF, -1 on error

    // Steps the currentLogEntry pointer forward one.
    // It handles both cases of preload and non-preload.
    // returns 0 on success, 1 on EOF, -1 on error
    virtual int advance_currentLogEntry(void);

    virtual int close_file(void);

    // }}}
    // {{{ handlers for VRPN control messages that might come from
    //     a File Controller object that wants to control this
    //     File Connection.
protected:
    static int VRPN_CALLBACK handle_set_replay_rate(void *, vrpn_HANDLERPARAM);
    static int VRPN_CALLBACK handle_reset(void *, vrpn_HANDLERPARAM);
    static int VRPN_CALLBACK handle_play_to_time(void *, vrpn_HANDLERPARAM);

    // }}}
    // {{{ Maintains a doubly-linked list structure that keeps
    //     copies of the messages from the file in memory.  If
    //     d_accumulate is false, then there is only ever one entry
    //     in memory (d_currentLogEntry == d_logHead == d_logTail).
    //     If d_preload is true, then all of the records from the file
    //     are read into the list in the constructor and we merely step
    //     through memory when playing the streamfile.  If d_preload is
    //     false and d_accumulate is true, then we have all of the
    //     records up the d_currentLogEntry in memory (d_logTail points
    //     to d_currentLogEntry but not to the last entry in the file
    //     until we get to the end of the file).
    //     The d_currentLogEntry should always be non-NULL unless we are
    //     past the end of all messages... we will either have preloaded
    //     all of them or else the read routine will attempt to load the
    //     next message each time one is played.  The constructor fills it
    //     in with the first message, which makes it non-NULL initially.
    //     HOWEVER, if there are no user messages and we're asked to skip
    //     to the first user message then it can be NULL right after the
    //     constructor is called.
protected:
    vrpn_LOGLIST *d_logHead;         // the first read-in record
    vrpn_LOGLIST *d_logTail;         // the last read-in record
    vrpn_LOGLIST *d_currentLogEntry; // Message that we've just loaded, or are
                                     // at right now
    vrpn_LOGLIST *d_startEntry; // potentially after initial system messages
    bool d_preload;             // Should THIS File Connection pre-load?
    bool d_accumulate;          // Should THIS File Connection accumulate?
                                // }}}
};

#endif // VRPN_FILE_CONNECTION_H