vrpn  07.33
Virtual Reality Peripheral Network
vrpn_Auxiliary_Logger.h
Go to the documentation of this file.
1 // This is a base class interface that has been designed for use by
2 // scientific data-collection applications that make use of VRPN to
3 // connect to microscope imagers and tracking system for nanoscale
4 // science research at UNC.
5 
6 // The idea of this interface is to enable a client GUI to start and
7 // stop logging of full-rate data on the server while receiving only
8 // a subset of the data during the experiment for preview; this keeps
9 // from overloading the network bandwidth with data and also keeps
10 // the client-side log files from filling up. When new log file(s)
11 // are requested, the old log files are closed.
12 
13 // Note that a particular implementation of the auxiliary logger server
14 // may need to know about a second connection (not the one it talks
15 // to its client over) in case that is where it is doing its logging.
16 
17 #ifndef VRPN_AUXILIARY_LOGGER_H
18 #define VRPN_AUXILIARY_LOGGER_H
19 #include <string.h> // for NULL
20 
21 #include "vrpn_BaseClass.h" // for vrpn_Callback_List, etc
22 #include "vrpn_Configure.h" // for VRPN_CALLBACK, VRPN_API
23 #include "vrpn_Connection.h"
24 #include "vrpn_Shared.h" // for timeval
25 #include "vrpn_Types.h" // for vrpn_int32
26 
28 public:
29  vrpn_Auxiliary_Logger(const char *name, vrpn_Connection *c);
30 
31 protected:
32  // Handle registration of all message types we're going to deal with.
33  virtual int register_types(void);
34  vrpn_int32 request_logging_m_id; // ID of remote->server request message
35  vrpn_int32 report_logging_m_id; // ID of server->client response message
36  vrpn_int32 request_logging_status_m_id; // ID of remote->server
37  // status-request message
38 
39  // Pack a log description into the message whose type is passed
40  // as the parameter (this is used to pack both the request and
41  // report messages.
42  bool pack_log_message_of_type(vrpn_int32 type,
43  const char *local_in_logfile_name,
44  const char *local_out_logfile_name,
45  const char *remote_in_logfile_name,
46  const char *remote_out_logfile_name);
47 
48  // Unpack a log description from a message into the four strings that
49  // were passed in (this is used to unpack both the request and the
50  // report messages).
51  // NOTE: This routine will allocate space for the strings. The caller
52  // must delete [] this space when they are done with it to avoid
53  // memory leaks.
54  bool unpack_log_message_from_buffer(const char *buf, vrpn_int32 buflen,
55  char **local_in_logfile_name,
56  char **local_out_logfile_name,
57  char **remote_in_logfile_name,
58  char **remote_out_logfile_name);
59 };
60 
61 // Virtual base server class for an auxiliiary logger. An implementation must
62 // implement the specified message-handling functions and must call the base-
63 // class constructor to set up the calling of them.
64 
66 public:
67  vrpn_Auxiliary_Logger_Server(const char *name, vrpn_Connection *c);
68 
69  // Required for servers.
70  virtual void mainloop(void) { server_mainloop(); }
71 
72 protected:
73  // Handle a logging-request message. The request contains four file
74  // names, two for local (to the Auxiliary server itself) and two for
75  // remote (the far side of its connection to the server). It must
76  // also respond to the client with a message saying what logging has
77  // been set up (using the send_logging_response function). Logging is
78  // turned off on a particular file by sending an empty-string name ("").
79  // The in/out local/remote are with respect to the connection that the
80  // logging is to occur on, which may or may not be the same one that the
81  // client has connected to the object on using the constructor above.
82  // Make sure to send a response saying what you did.
83  virtual void
84  handle_request_logging(const char *local_in_logfile_name,
85  const char *local_out_logfile_name,
86  const char *remote_in_logfile_name,
87  const char *remote_out_logfile_name) = 0;
88 
89  // Send a response to the client telling it what logging has been
90  // established.
91  bool send_report_logging(const char *local_in_logfile_name,
92  const char *local_out_logfile_name,
93  const char *remote_in_logfile_name,
94  const char *remote_out_logfile_name)
95  {
96  if (!d_connection) {
97  return false;
98  }
100  report_logging_m_id, local_in_logfile_name, local_out_logfile_name,
101  remote_in_logfile_name, remote_out_logfile_name);
102  }
103 
104  // Handle dropped last connection on server object by turning off
105  // logging. The static method basically looks up the this
106  // pointer and calls the virtual method. A derived class should
107  // re-implement the non-static method below if it doesn't want to drop all
108  // logging or if it wants to do something else in addition. The static
109  // method basically just calls the non-static method.
110  virtual void handle_dropped_last_connection(void);
111  vrpn_int32 dropped_last_connection_m_id; // ID of message that all
112  // connections dropped
113  static int VRPN_CALLBACK
114  static_handle_dropped_last_connection(void *userdata, vrpn_HANDLERPARAM p);
115 
116  // Static portion of handling (unpacking) the request_logging message. It
117  // then calls the non-static virtual method above.
118  static int VRPN_CALLBACK
119  static_handle_request_logging(void *userdata, vrpn_HANDLERPARAM p);
120 
121  // Handle request for logging status.
122  virtual void handle_request_logging_status() = 0;
123  static int VRPN_CALLBACK
124  static_handle_request_logging_status(void *userdata, vrpn_HANDLERPARAM p);
125 };
126 
127 // Generic server that will start auxiliary logs on the connection whose name
128 // is passed in (which can be the same as the name of the connection it is
129 // created on, but does not have to be). The "local" in and out are with
130 // respect to the new connection that is made; the "remote" in and out are with
131 // respect to the named connection. No logging is started in the constructor.
132 
135 public:
136  // Does not start logging, just records what to log when it is started.
137  vrpn_Auxiliary_Logger_Server_Generic(const char *logger_name,
138  const char *connection_to_log,
139  vrpn_Connection *c = NULL);
141 
142  // Close an existing logging connection, then (if any of the file
143  // names are non-empty) open a new logging connection to the
144  // connection we are to log (even if this process already has a
145  // connection to it) and then send back the report that we've started
146  // logging if we are able. If we cannot open it, then fill in all
147  // blank names for the return report.
148  virtual void handle_request_logging(const char *local_in_logfile_name,
149  const char *local_out_logfile_name,
150  const char *remote_in_logfile_name,
151  const char *remote_out_logfile_name);
152 
153  virtual void handle_request_logging_status();
154 
155  // If we have an active logging connection, mainloop it and save all of its
156  // pending messages in addition to handling the base-class functions.
157  // Then call the parent class mainloop().
158  virtual void mainloop(void)
159  {
160  if (d_logging_connection) {
161  d_logging_connection->mainloop();
162  d_logging_connection->save_log_so_far();
163  }
165  }
166 
167 protected:
168  char *d_connection_name; // Name to connect to when logging.
169  vrpn_Connection *d_logging_connection; // Connection to use for logging.
170 };
171 
172 //-----------------------------------------------------------
173 //************** Client code uses the following *************
174 
175 // Type of a client routine to request new logging and to handle a
176 // report of changed logging. This callback is called when the
177 // logging server reports a new set of files, which should happen
178 // after each request is made.
179 
180 typedef struct _vrpn_AUXLOGGERCB {
181  struct timeval msg_time; // Timestamp of new logging
182  const char *
183  local_in_logfile_name; // Name of the incoming local log ("" if none).
187 } vrpn_AUXLOGGERCB;
188 
190  void *userdata, const vrpn_AUXLOGGERCB info);
191 
193 public:
194  vrpn_Auxiliary_Logger_Remote(const char *name, vrpn_Connection *c = NULL);
195 
196  // Send a request to the server asking it to log the following. Each of
197  // these is with respect to the connection that the auxiliary logger server
198  // is handling, which may or may not be the one that it is connected to to
199  // receive this message; it refers to the other side of the new connection
200  // that the server establishes to do its logging. Passing a NULL or empty
201  // string ("") to any of the entries disables that log.
202  // WARNING: If the server is set to connect to its own connection and log
203  // it, then you must explicitly request a set of empty log files to stop
204  // it logging the last time because otherwise it never gets the message
205  // that it dropped the last connection and will continue logging after the
206  // object is destroyed.
207  bool send_logging_request(const char *local_in_logfile_name,
208  const char *local_out_logfile_name = "",
209  const char *remote_in_logfile_name = "",
210  const char *remote_out_logfile_name = "")
211  {
212  if (!d_connection) {
213  return false;
214  }
216  request_logging_m_id, local_in_logfile_name, local_out_logfile_name,
217  remote_in_logfile_name, remote_out_logfile_name);
218  }
219 
221  {
222  if (!d_connection) {
223  return false;
224  }
225  return pack_log_message_of_type(request_logging_status_m_id, NULL, NULL,
226  NULL, NULL);
227  }
228 
229  // Register/unregister a callback handler for the logging response.
230  virtual int register_report_handler(void *userdata,
232  {
233  return d_callback_list.register_handler(userdata, handler);
234  };
235  virtual int unregister_report_handler(void *userdata,
237  {
238  return d_callback_list.unregister_handler(userdata, handler);
239  }
240 
241  // This routine calls the mainloop of the connection it's on
242  virtual void mainloop(void);
243 
244 protected:
245  // Static handler for the logging report message.
246  // Use the base-class unpack method to convert the data into strings.
248 
249  static int VRPN_CALLBACK
250  handle_report_message(void *userdata, vrpn_HANDLERPARAM p);
251 };
252 
253 #endif
vrpn_BaseClass.h
vrpn_Types.h
vrpn_Auxiliary_Logger_Server_Generic::mainloop
virtual void mainloop(void)
Called once through each main loop iteration to handle updates. Remote object mainloop() should call ...
Definition: vrpn_Auxiliary_Logger.h:158
vrpn_Auxiliary_Logger_Server::handle_request_logging_status
virtual void handle_request_logging_status()=0
vrpn_Auxiliary_Logger_Remote::unregister_report_handler
virtual int unregister_report_handler(void *userdata, vrpn_AUXLOGGERREPORTHANDLER handler)
Definition: vrpn_Auxiliary_Logger.h:235
vrpn_Auxiliary_Logger_Server::dropped_last_connection_m_id
vrpn_int32 dropped_last_connection_m_id
Definition: vrpn_Auxiliary_Logger.h:111
vrpn_Auxiliary_Logger_Server::handle_request_logging
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
vrpn_Callback_List< vrpn_AUXLOGGERCB >
vrpn_Auxiliary_Logger::pack_log_message_of_type
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)
Definition: vrpn_Auxiliary_Logger.C:34
_vrpn_AUXLOGGERCB::local_in_logfile_name
const char * local_in_logfile_name
Definition: vrpn_Auxiliary_Logger.h:183
vrpn_Auxiliary_Logger::report_logging_m_id
vrpn_int32 report_logging_m_id
Definition: vrpn_Auxiliary_Logger.h:35
vrpn_Auxiliary_Logger_Server_Generic::d_logging_connection
vrpn_Connection * d_logging_connection
Definition: vrpn_Auxiliary_Logger.h:169
vrpn_Auxiliary_Logger_Server::mainloop
virtual void mainloop(void)
Called once through each main loop iteration to handle updates. Remote object mainloop() should call ...
Definition: vrpn_Auxiliary_Logger.h:70
vrpn_Auxiliary_Logger_Remote::send_logging_request
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="")
Definition: vrpn_Auxiliary_Logger.h:207
vrpn_Auxiliary_Logger_Remote::register_report_handler
virtual int register_report_handler(void *userdata, vrpn_AUXLOGGERREPORTHANDLER handler)
Definition: vrpn_Auxiliary_Logger.h:230
vrpn_HANDLERPARAM
This structure is what is passed to a vrpn_Connection message callback.
Definition: vrpn_Connection.h:44
vrpn_Auxiliary_Logger_Server_Generic::d_connection_name
char * d_connection_name
Definition: vrpn_Auxiliary_Logger.h:168
vrpn_Shared.h
vrpn_Auxiliary_Logger_Remote::d_callback_list
vrpn_Callback_List< vrpn_AUXLOGGERCB > d_callback_list
Definition: vrpn_Auxiliary_Logger.h:247
vrpn_Auxiliary_Logger::request_logging_m_id
vrpn_int32 request_logging_m_id
Definition: vrpn_Auxiliary_Logger.h:34
vrpn_BaseClass::mainloop
virtual void mainloop()=0
Called once through each main loop iteration to handle updates. Remote object mainloop() should call ...
vrpn_Auxiliary_Logger
Definition: vrpn_Auxiliary_Logger.h:27
vrpn_Auxiliary_Logger_Server_Generic
Definition: vrpn_Auxiliary_Logger.h:133
vrpn_Connection
Generic connection class not specific to the transport mechanism.
Definition: vrpn_Connection.h:510
_vrpn_AUXLOGGERCB::remote_in_logfile_name
const char * remote_in_logfile_name
Definition: vrpn_Auxiliary_Logger.h:185
vrpn_Connection.h
_vrpn_AUXLOGGERCB::msg_time
struct timeval msg_time
Definition: vrpn_Auxiliary_Logger.h:181
vrpn_BaseClass::register_types
virtual int register_types(void)=0
Register the types of messages this device sends/receives. Return 0 on success, -1 on fail.
VRPN_CALLBACK
#define VRPN_CALLBACK
Definition: vrpn_Configure.h:647
vrpn_Auxiliary_Logger_Remote
Definition: vrpn_Auxiliary_Logger.h:192
vrpn_Configure.h
vrpn_Auxiliary_Logger_Server::send_report_logging
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)
Definition: vrpn_Auxiliary_Logger.h:91
_vrpn_AUXLOGGERCB::local_out_logfile_name
const char * local_out_logfile_name
Definition: vrpn_Auxiliary_Logger.h:184
vrpn_Auxiliary_Logger_Server
Definition: vrpn_Auxiliary_Logger.h:65
vrpn_Auxiliary_Logger::request_logging_status_m_id
vrpn_int32 request_logging_status_m_id
Definition: vrpn_Auxiliary_Logger.h:36
vrpn_Auxiliary_Logger_Remote::send_logging_status_request
bool send_logging_status_request()
Definition: vrpn_Auxiliary_Logger.h:220
VRPN_API
#define VRPN_API
Definition: vrpn_Configure.h:646
_vrpn_AUXLOGGERCB
Definition: vrpn_Auxiliary_Logger.h:180
vrpn_BaseClassUnique::server_mainloop
void server_mainloop(void)
Handles functions that all servers should provide in their mainloop() (ping/pong, for example) Should...
Definition: vrpn_BaseClass.C:603
vrpn_BaseClass
Class from which all user-level (and other) classes that communicate with vrpn_Connections should der...
Definition: vrpn_BaseClass.h:313
_vrpn_AUXLOGGERCB::remote_out_logfile_name
const char * remote_out_logfile_name
Definition: vrpn_Auxiliary_Logger.h:186
vrpn_AUXLOGGERREPORTHANDLER
void(VRPN_CALLBACK * vrpn_AUXLOGGERREPORTHANDLER)(void *userdata, const vrpn_AUXLOGGERCB info)
Definition: vrpn_Auxiliary_Logger.h:189