/*
 * File:
 *   clio.h
 * Summary:
 *   Type and function declarations useful for Clio3D
 * Author:
 *   Samuel A. Rebelsky
 * Version:
 *   0.1 of July 2003.
 */

#ifndef _CLIO_H_
#define _CLIO_H_

/***********************************************************************
 * Design Notes *
 ****************/

/*

1. The interface is responsible for setting the value of a number
of function pointers (e.g., getX, getY, ...) to appropriate functions
(e.g., getStartTime, getPageID, ...).

2. A global table (visits) and integer variable (numvisits) store
information on all the visits.  

3. The procedure that is responsible for building that table is
also responsible for making sure that values are "reasonable" 
(e.g., that session and browser ids get mapped to the range [1..n]
rather than whatever they were originally.)

4. We have two different ways of classifying most of the table data.
Some can be classified as "continuous", in which case the corresponding
function gives a real number between 0 and 100.  Some can be classified
as "discrete", in which case the corresopnding function gives an integer
between 0 and 5.

5. Stubs for many of the primary files can be found by replacing
"clio" by "stub".  For example, the replacment for "cliodata.c" is
"stubdata.c".

*/


/***********************************************************************
 * Headers *
 ***********/

#include <stdlib.h>	/* All friendly C programs use stdlib. */
#include <stdio.h>	/* Yes, we may read and write stuff. */
#include <GL/glut.h>	/* Most importantly, we're using OpenGL
			   and the GLUT. */


/***********************************************************************
 * Types *
 *********/

/*
 * The type used to record page visits.
 */
typedef struct pagevisit {
  int visitid;	/* A unique ID for the visit.  Probably unused. */
  int userid;	/* The id of the user. */
  int pageid;	/* The id of the page visited. Should be converted */
		/* to a reasonable range. */
  int windowid;	/* The id of the window visited.  Should be converted
		   to a reasonable range. */
  int sessionid;/* The id of the session.  Should be converted to a
		   reasonable range. */
  int uws;	/* Hybrid of user, window, and session.  Should be
		   converted to a reasonable range. */
  int start;	/* The time at which the user started reading the page.
		   Probably represented in "seconds since ...".  Need
		   not be converted. */
  int length;	/* The amount of time the user spent on the page,
		   in seconds. */
  int type;	/* The type of page, converted to an integer in a 
		   reasonable range. */
} pagevisit;

/*
 * Restrictions on queries for selecting data.
 */
typedef struct selector {
  int *users;	/* An array of user ids of all users to be selected. */
  int numusers;	/* The number of user ids in that array. */
  int start;	/* The starting time of the entries to be selected. */
  int end;	/* The ending time of the entries to be selected. */
} selector;

/*
 * Functions that look at pagevisits and return continuous
 * values in the range [0..100].
 */
typedef float (*continuous)(pagevisit *);

/*
 * Functions that look at pagevisits and return discrete
 * values in the range [0..4].
 */
typedef int (*discrete)(pagevisit *);


/*********************************************************************
 * Constants *
 *************/

/* The maximum continous value. */
#define MAXC 100.0

/* The maximum discrete values. */
#define MAXD 5


/*********************************************************************
 * Shared Variables *
 ********************/

/**************
 * cliodata.c *
 **************/

/* The complete record of visits to be displayed. */
extern pagevisit *visits;

/* 
 * The number of entries in that array (since C does not give us
 * any convenient way to get that number).
 */
extern int numvisits;

/*
 * The smallest start time of a visit.
 */
extern int starttime;

/*
 * The largest end time of a visit.
 */
extern int endtime;
 
/*
 * The number of different page types.
 */
extern int pagetypes; 

/*
 * The maximum length of any page visit.
 */
extern int maxlength;


/*********************************************************************
 * Functions *
 *************/

/**************
 * cliodata.c *
 **************/

/*
 * Load data using some appropriate technique, limiting the data
 * loaded to those specified by query.
 */
extern void loadData(selector *query);


/****************
 * extractors.c *
 ****************/

extern float getLengthC(pagevisit *);
extern int getLengthD(pagevisit *);
extern float getPageC(pagevisit *);
extern int getPageD(pagevisit *);	/* Not a good idea. */
extern float getStartC(pagevisit *);
extern int getStartD(pagevisit *);
extern float getTypeC(pagevisit *);
extern int getTypeD(pagevisit *);
extern float getUWSC(pagevisit *);
extern int getUWSD(pagevisit *);

extern float getConstant0C(pagevisit *);
extern int getConstant0D(pagevisit *);
extern float getConstant5C(pagevisit *);
extern int getConstant5D(pagevisit *);
extern float getConstant10C(pagevisit *);
extern int getConstant10D(pagevisit *);
extern float getConstant100C(pagevisit *);
extern int getConstant100D(pagevisit *);


/******************
 * cliosettings.c *
 ******************/

extern continuous getX;
extern continuous getY;
extern continuous getZ;
extern continuous getW;
extern continuous getH;
extern continuous getD;
extern continuous getShade;
extern discrete getColor;
extern discrete getShape;


/*************
 * cliovis.c *
 *************/

extern void cityScape();
extern void boxesInSpace();


#endif /* _CLIO_H_ */