<?php
//$Header: /hl/cvsroots/gpl01/gpl01/webprojs/fboprime/sw/phplib/par.inc,v 1.9 2006/08/01 21:51:46 dashley Exp $
//********************************************************************************
//par.inc--FboPrime Parameter and Cookie Processing
//Copyright (C) 2006  David T. Ashley
//
//This program is free software; you can redistribute it and/or
//modify it under the terms of the GNU General Public License
//as published by the Free Software Foundation; either version 2
//of the License, or (at your option) any later version.
//
//This program is distributed in the hope that it will be useful,
//but WITHOUT ANY WARRANTY; without even the implied warranty of
//MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
//GNU General Public License for more details.
//
//You should have received a copy of the GNU General Public License
//along with this program; if not, write to the Free Software
//Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
//********************************************************************************
//This file contains functions that carefully control GET/POST input parameters
//and cookies and bring them into the global variable space.
//
//The most conservative approach is to restrict such parameters to a language,
//i.e. to confine the form they may have.
//--------------------------------------------------------------------------------
require_once("strfunc.inc");
//
//--------------------------------------------------------------------------------
//FULL LIST OF COOKIE PARAMETERS
//------------------------------
//Only one cookie is issued by this software, named "fbopsid".  This is a session
//identifier as described in the documentation.  The cookie is issued on a
//successful login and revoked when a session times out or there is an
//authentication failure.
//
//--------------------------------------------------------------------------------
//FULL LIST OF GET/POST PARAMETERS
//--------------------------------
//This is the list of get/post parameters.  They are named uniquely to avoid
//confusion or mistakes.  In general, a script will try to import only those
//parameters that it is interested in--others are ignored.
//
//GET and POST parameters are usually treated identically--there is no 
//differentiation made.  This means in some cases it is possible to modify page 
//behavior (for example, page appearance) by adding a string to the URL (i.e. to 
//use a URL not directly generated by the software).  This allows power-users
//to sometimes work more effectively.
//
//GET parameters are preferentially used, as they allow URLs to be bookmarked
//and e-mailed.
//
//index.php -- Main scheduler day view.
//-------------------------------------
//   authuserid
//      The login name of the user.  For example, "jsmith".  Login names
//      must begin with a letter, must be 20 characters or less, and may
//      contain only letters and numbers.  Login names are converted to
//      all lower-case, and they are treated as case-insensitive.
//
//      Any supplied parameter has blanks and invalid characters removed
//      before being assigned to the global variable.  In some cases,
//      a login name consisting of exclusively blanks or invalid characters
//      may be assigned to the global variable as the empty string.
//
//      If the login name is not supplied, the corresponding global
//      variable is set to FALSE.
//
//   authuserpasswd
//      The password supplied by the user to authenticate.  Passwords
//      may contain only certain characters, no spaces at the ends, etc.
//
//      Any supplied parameter has blanks and invalid characters removed
//      before being assigned to the global variable.  In some cases,
//      password consisting of exclusively blanks or invalid characters
//      may be assigned to the global variable as the empty string.
//
//      If the password is not supplied, the corresponding global
//      variable is set to FALSE.
//
//   logout
//      If the main scheduling page is invoked with a get or post
//      parameter of "logout" defined to _any_ value, this is a cue
//      to log out the user.  The traditional value is logout=1.
//
//      A user is logged out by linking to the main scheduling page
//      with the "logout" parameter set.
//
//   sddt
//      The date whose scheduling information will be displayed.
//
//      If no date is supplied, the default is usually the current
//      calendar day.
//
//      The date is in the format YYYYMMDD, for example,
//
//         "20060408".
//
//      Any supplied parameter has blanks and invalid characters removed
//      before being assigned to the global variable.  In some cases,
//      a date consisting of exclusively blanks or invalid characters
//      may be assigned to the global variable as the empty string.
//
//      If the date is not supplied, the corresponding global
//      variable is set to FALSE.
//
//   sdtim
//      The time of day for which scheduling information should be
//      displayed.
//
//      If no time of day is supplied, the default is usually
//      the default panel for scheduling views.
//
//      The time is in the format "HHMMSS", for example,
//
//         "1519".
//
//      The time should range from "0000" through "2359".  "2400" is
//      illegal, as it would actually correspond to midnight of the
//      following day.
//
//      Any supplied parameter has blanks and invalid characters removed
//      before being assigned to the global variable.  In some cases,
//      a date consisting of exclusively blanks or invalid characters
//      may be assigned to the global variable as the empty string.
//
//      If the date is not supplied, the corresponding global
//      variable is set to FALSE.
//
//   todaynow
//      If set to any value (i.e. if it exists), the global variable is
//      set to TRUE, otherwise, it is set to FALSE.  Signals that current
//      server time should be used (all get/post parameters and session
//      state should be ignored).
//
//   menulvladjst
//      If present, indicates to adjust the current menu level (stored in
//      the session record of the database) up or down.  Parameter values
//      allowed:
//         "D" (or "d")  :  Decrement the current menu level (corresponding
//                          to fewer options displayed).
//         "U" (or "u")  :  Increment the current menu level (corresponding
//                          to more options displayed).
//
//   acklevel
//      Used for acknowledgement screens in various contexts, to trigger
//      an acknowledgement screen rather than the main action.  This should
//      be an integer in the range of [0,100] with semantics defined by
//      the using page.  If the parameter is missing or invalid, $PAR_acklevel
//      is assigned FALSE.
//
//--------------------------------------------------------------------------------
//Obtains the FBOPSID cookie parameter and assigns it to a global variable.
//FALSE is assigned if the parameter is not passed.  Invalid characters are 
//removed, possibly leading to the empty string if the passed entity is empty or
//contains only invalid characters.
//
function PAR_get_fbopsid()
   {
   global $PAR_fbopsid;

   if (! isset($_COOKIE["fbopsid"]))
      {
      $PAR_fbopsid = FALSE;
      return;
      }
   else
      {
      $PAR_fbopsid = $_COOKIE["fbopsid"];
      }

   //Trim the string down to the characters allowed for a session identifier.
   $PAR_fbopsid = STRFUNC_force_into_subset($PAR_fbopsid, "SGIABCDEF0123456789");

   //The total string may be no longer than 66 characters long.
   if (strlen($PAR_fbopsid) > 66)
      {
      $PAR_fbopsid = SubStr($PAR_fbopsid, 0, 66);
      }
   }
//
//
//--------------------------------------------------------------------------------
//Obtains the AUTHUSERID and assigns it into a global variable.  FALSE is 
//assigned if the parameter is not passed.  Invalid characters are removed, 
//possibly leading to the empty string if the passed entity is empty or
//contains only invalid characters.
//
//Unit-tested on 20060408.
//
function PAR_get_authuserid()
   {
   global $PAR_authuserid;

   if ((! isset($_GET["authuserid"])) && (! isset($_POST["authuserid"])))
      {
      $PAR_authuserid = FALSE;
      return;
      }
   else if (isset($_POST["authuserid"]))
      {
      $starting_point = $_POST["authuserid"];
      }
   else if (isset($_GET["authuserid"]))
      {
      $starting_point = $_GET["authuserid"];
      }

   //Trim all disallowed characters.
   $starting_point 
      = STRFUNC_force_into_subset($starting_point, 
                                  "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789");

   //Force the string to be all lower case.
   $starting_point = StrToLower($starting_point);

   //If the string is now of zero length, treat this parameter
   //as not existing.
   if (strlen($starting_point) == 0)
      { 
      $PAR_authuserid = FALSE;
      return;
      }

   //And assign to the global, which we may be just newly creating.
   $PAR_authuserid = $starting_point;
   }
//
//
//--------------------------------------------------------------------------------
//Obtains the AUTHUSERPASSWD and assigns it into a global variable.  FALSE is 
//assigned if the parameter is not passed.  Invalid characters are removed, 
//possibly leading to the empty string if the passed entity is empty or
//contains only invalid characters.
//
//Passwords are not trimmed here.  The password is never displayed (so HTML
//encoded scripting attacks, etc. shouldn't be possible), and it is better
//if downstream software can parse it and potentially display error
//messages.
//
//Passwords will only be accepted as a POST parameter (they should not be
//on the command line.
//
function PAR_get_authuserpasswd()
   {
   global $PAR_authuserpasswd;

   if (! isset($_POST["authuserpasswd"]))
      {
      $PAR_authuserpasswd = FALSE;
      return;
      }

   $PAR_authuserpasswd = $_POST["authuserpasswd"];
   }
//
//
//--------------------------------------------------------------------------------
//Obtains the SDDT and assigns it into a global variable.  FALSE is 
//assigned if the parameter is not passed.  Invalid characters are removed, 
//possibly leading to the empty string if the passed entity is empty or
//contains only invalid characters.
//
//Unit-tested on 20060408.
//
function PAR_get_sddt()
   {
   global $PAR_sddt;

   if ((! isset($_GET["sddt"])) && (! isset($_POST["sddt"])))
      {
      $PAR_sddt = FALSE;
      return;
      }
   else if (isset($_POST["sddt"]))
      {
      $starting_point = $_POST["sddt"];
      }
   else if (isset($_GET["sddt"]))
      {
      $starting_point = $_GET["sddt"];
      }

   //Trim all disallowed characters.
   $starting_point 
      = STRFUNC_force_into_subset($starting_point, 
                                  "0123456789");

   //And assign to the global, which we may be just newly creating.
   $PAR_sddt = $starting_point;
   }
//
//
//--------------------------------------------------------------------------------
//Obtains the SDTIM and assigns it into a global variable.  FALSE is 
//assigned if the parameter is not passed.  Invalid characters are removed, 
//possibly leading to the empty string if the passed entity is empty or
//contains only invalid characters.
//
//Unit-tested on 20060408.
//
function PAR_get_sdtim()
   {
   global $PAR_sdtim;

   if ((! isset($_GET["sdtim"])) && (! isset($_POST["sdtim"])))
      {
      $PAR_sdtim = FALSE;
      return;
      }
   else if (isset($_POST["sdtim"]))
      {
      $starting_point = $_POST["sdtim"];
      }
   else if (isset($_GET["sdtim"]))
      {
      $starting_point = $_GET["sdtim"];
      }

   //Trim all disallowed characters.
   $starting_point 
      = STRFUNC_force_into_subset($starting_point, 
                                  "0123456789");

   //And assign to the global, which we may be just newly creating.
   $PAR_sdtim = $starting_point;
   }
//
//
//--------------------------------------------------------------------------------
//Obtains the TODAYNOW and assigns it into a global variable.  TRUE is assigned
//if ANY value is present for the variable, or FALSE otherwise.
//
function PAR_get_todaynow()
   {
   global $PAR_todaynow;

   if ((isset($_GET["todaynow"])) || (isset($_POST["todaynow"])))
      {
      $PAR_todaynow = TRUE;
      }
   else
      {
      $PAR_todaynow = FALSE;
      }
   }
//
//
//--------------------------------------------------------------------------------
//Obtains the MENULVLADJST and assigns it into a global variable as either:
//   FALSE if the parameter is not passed.
//   -1    if the menu level is to be decremented.
//    1    if the menu level is to be incremented.
//
function PAR_get_menulvladjst()
   {
   global $PAR_menulvladjst;

   if ((! isset($_GET["menulvladjst"])) && (! isset($_POST["menulvladjst"])))
      {
      $PAR_menulvladjst = FALSE;
      return;
      }
   else if (isset($_POST["menulvladjst"]))
      {
      $starting_point = $_POST["menulvladjst"];
      }
   else if (isset($_GET["menulvladjst"]))
      {
      $starting_point = $_GET["menulvladjst"];
      }

   //Trim all disallowed characters.
   $starting_point = STRFUNC_force_into_subset($starting_point, "uUdD");

   //And assign to the global, which we may be just newly creating.
   if (($starting_point == "d") || ($starting_point == "D"))
      $PAR_menulvladjst = -1;
   else if (($starting_point == "u") || ($starting_point == "U"))
      $PAR_menulvladjst =  1;
   else
      $PAR_menulvladjst =  FALSE;
   }
//
//
//--------------------------------------------------------------------------------
//Obtains the LOGOUT parameter.  If this parameter is set to ANY value,
//it is a cue to log out the user.
//
function PAR_get_logout()
   {
   global $PAR_logout;

   if ((! isset($_GET["logout"])) && (! isset($_POST["logout"])))
      {
      $PAR_logout = FALSE;
      }
   else
      {
      $PAR_logout = TRUE;
      }
   }
//
//
//--------------------------------------------------------------------------------
//Obtains the ACKLEVEL and assigns it into a global variable as an integer.  
//FALSE is assigned if the parameter is not passed or if it is passed but is
//invalid.
//
function PAR_get_acklevel()
   {
   global $PAR_acklevel;

   if ((! isset($_GET["acklevel"])) && (! isset($_POST["acklevel"])))
      {
      $PAR_acklevel = FALSE;
      return;
      }
   else if (isset($_POST["acklevel"]))
      {
      $starting_point = $_POST["acklevel"];
      }
   else if (isset($_GET["acklevel"]))
      {
      $starting_point = $_GET["acklevel"];
      }

   //Trim all disallowed characters.
   $starting_point = STRFUNC_force_into_subset($starting_point, "0123456789");

   //Remove any leading zeros.
   while ((strlen($starting_point) > 1) && (SubStr($starting_point, 0, 1) == "0"))
      $starting_point = SubStr($starting_point, 1);
 
   //At this point, the value can't help but syntactically be an integer or the
   //empty string.
   if (strlen($starting_point) == 0)
      {
      $PAR_acklevel = FALSE;          //Empty string.
      }
   else if (strlen($starting_point) > 2)
      {
      $PAR_acklevel = FALSE;          //Too big as an integer.
      }
   else
      {
      $starting_point = (int)$starting_point;
      if (($starting_point >= 0) && ($starting_point <= 100))
         {
         $PAR_acklevel = $starting_point;
         }
      else
         {
         $PAR_acklevel = FALSE;          //Out of range as an integer.
         }
      }
   }
//
//
//--------------------------------------------------------------------------------
//End of $RCSfile: par.inc,v $.
//--------------------------------------------------------------------------------
?>