rdTeleport Class Reference

All of the Routines to Control the Teleporter Database. More...

Public Member Functions
	rdSelectDestinations ($SqlQuery, $Parameters, $Pdo, $ThisWorld, $ThisRegion)
	Print out the selected teleporters for the Destination Notecard.
	rdConfirmUser ($UseSimDb, $PDO, $PDO1)
	Fucntion to confirm that the object's owner is authorise to run script.
	rdOpenDatabase ($Database, $Host, $Username, $Password)
	Open the Support Database for Use.
	rdProcessTeleport ()
	The public function that does all the work.

Detailed Description

All of the Routines to Control the Teleporter Database.

Definition at line 30 of file teleport.php.

Member Function Documentation

rdConfirmUser()

rdTeleport::rdConfirmUser	(		$UseSimDb,
			$PDO,
			$PDO1 )

Fucntion to confirm that the object's owner is authorise to run script.

Parameters

$UseSimDb	Flag to indicate if the OpenSim database UserAccounts is to be used
$PDO	The database instance to access the local ls_os_teleport_allowed table
$PDO1	The database instance to access the OpenSim UserAccounts table

This routine checks if it is allowed to access the OpenSim database UserAccounts file to determine if the owner of this object is known. If it is, and the user is found, the routine exits.

If the UserAccounts file cannot be used, or the user is not found in that file, the local ls_os_teleport_allowed table is queried. If the owner cannot be found in that table, then the script will abort.

If the user ias found in that table, the routine will set the world where the user exists and whether that user is currently allowed to change the contents of the teleporter table.

Definition at line 113 of file teleport.php.

    {
        global $remote_world; global $teleport_allowed; global $readings;
        
        $not_known = TRUE;
        
        //============================================================================
        // If the Simulator Database is available, confirm the teleporter owner is known
        //============================================================================
        if ($UseSimDb)
        {
            $sql_query = "select PrincipalId from UserAccounts where PrincipalId = :key";
            $stmt = $PDO1->prepare($sql_query);
            $stmt->execute(['key' => $readings['owner']]);
            $is_user = $stmt->fetch(PDO::FETCH_ASSOC);
            if ($is_user)
            {
                $not_known = FALSE;     
            }
        }       
        
        //============================================================
        // Check if the User is in the Support Allowed Table
        //============================================================
        if ($not_known)
        {
            $sql_query = "select * from ls_os_teleport_allowed where teleport_owner = :key and teleport_world = :world";
            $stmt = $PDO->prepare($sql_query);
            $stmt->execute(['key' => $readings['owner'], 'world' => $readings['world']]);
            $is_user = $stmt->fetch(PDO::FETCH_ASSOC);
            if (!$is_user)
            {
                die("FAILURE=BANNED|Teleporter Owner ". $readings['owner']. " is unknown\n");
            }
            else
            {
                $remote_world = $is_user['teleport_world'];
                $is_allowed = $is_user['teleport_allowed'];
            }
        }
    }

References $readings.

Referenced by rdProcessTeleport().

Here is the caller graph for this function:

rdOpenDatabase()

rdTeleport::rdOpenDatabase	(		$Database,
			$Host,
			$Username,
			$Password )

Open the Support Database for Use.

Parameters

$Database	The Name of the Database to Open
$Host	The name of the computer use to conenct to the Database
$Username	The username to access the Database
$Password	The password to access the database.

If this routine fails, it will case the program to abort and the heartbeat will neither identify itself as being on-line and it will not update the list of destinations.

Definition at line 170 of file teleport.php.

    {
        // Data Source Name (DSN) string
        $dsn = "mysql:host=$Host;dbname=$Database;charset=utf8mb4";
 
        // Set PDO options for better error handling and security
        $options = [
                PDO::ATTR_ERRMODE            => PDO::ERRMODE_EXCEPTION, // Throw exceptions on errors
                PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,       // Set default fetch mode to associative array
                PDO::ATTR_EMULATE_PREPARES   => true,                  // Disable emulated prepares for better security
               ];
 
        try
        {
            // Create a new PDO connection instance
            $pdo = new PDO($dsn, $Username, $Password, $options);    
        }
        catch (PDOException $e)
        {
            // Catch the exception and display a user-friendly error message
            // In a production environment, you might log the specific error
            
            die("FAILURE=DATABASE:Connection failed " . $e->getMessage());
        }
        
        return $pdo;
    }

Referenced by rdProcessTeleport().

Here is the caller graph for this function:

rdProcessTeleport()

rdTeleport::rdProcessTeleport

(

)

The public function that does all the work.

The function has three main activities:

(1) Insert new teleporters into the database;
(2) Update existing teleporter entries in the database, including the heartbeat time.
(3) Scan teleporter database for potentially dead teleporters and remove if required.

Definition at line 213 of file teleport.php.

    {
        global $readings;
 
        //=================================================================================
        // Initialise Constants and Pre-set Variables 
        //=================================================================================
 
        // Define what a NULL KEY actually is.
        $NULL_KEY = (string)'00000000-0000-0000-0000-000000000000';
 
        // Initialise the List of Teleport Destinations
        $teleporter = [];
 
        $allow_outsiders = FALSE;
 
        $LOCAL_LOCATION     = "GROUP";
        $REGION_LOCATION    = "REGION";
        $WORLD_LOCATION     = "WORLD";
        $METAVERSE_LOCATION = "METAVERSE";
 
        $GROUP_FLAG     =  1;
        $REGION_FLAG    =  2;
        $WORLD_FLAG     =  4;
        $METAVERSE_FLAG =  8;
 
        $LOCATION_MASK = $GROUP_FLAG | $REGION_FLAG | $WORLD_FLAG | $METAVERSE_FLAG;
 
        $ANONYMOUS_FLAG = 16;
                
        $pdo; $pdo1;
        $remote_world = "";
        $teleport_allowed = FALSE;
        
        //=================================================================================
        //= Define if the Simulator's working databse will be accessed
        //=================================================================================
        $use_sim_db = TRUE;
 
        //=================================================================================
        // Set whether addresses outside of the home world of this program are allowed
        //=================================================================================
        // If this value is set to FALSE, teleporters out side of the home world of this
        // simulator are not allowed to access the database.
        //=================================================================================
        $allow_outsiders = FALSE;
 
        //=================================================================================
        // Connect to the Required Databases
        //=================================================================================
        
        global $db; global $host; global $db_username; global $db_password;
        global $db1; global $host1; global $db1_username; global $db1_password;
        global $pdo; global $pdo1; global $remote_world; global $readings;     
        
        // Connect to the Support Database
        $pdo = $this->rdOpenDatabase($db, $host, $db_username, $db_password);
 
        // Connect to the Simulator's database if it is to be used
 
        if ($use_sim_db) $pdo1 = $this->rdOpenDatabase($db1, $host1, $db1_username, $db1_password);
 
        
        //==================================================================================
        // Confirnm the User & Get World and Permission
        //==================================================================================
        
        $this->rdConfirmUser($use_sim_db, $pdo, $pdo1);
        
        //=================================================================================
        // Check if this is a Heartbeat Command
        //=================================================================================
            
        // Process the Parameters if the Command is "heartbeat"
        if ($readings['command'] == "heartbeat")
        {
            //##############################################################################
            //# Determine if External Worlds are Allowed to Access the Teleporter Dataabse #
            //##############################################################################
            if ($remote_world != "" && (!is_allowed || !$allow_outsiders))
            {
                die("FAILURE=BANNED|Teleporter Owner ". $readings['owner']. "@".$readings['world']." is not authorised\n");
            }
                
            //############################################################################
            //# Decode the Array Information that has been pass in.                      #
            //############################################################################
 
            // Decode the Position array into the $position array. 0->x, 1->y, 2->z
                $position_string = substr($readings['position'], 1, -1);    // Remove leading and trailing angle brackets
                $pos = explode(",", $position_string);
                $position = array_slice($pos, 0, 3);
                        
            // Decode the Rotation into the rotation array. 0->x, 1->y, 2->z, 3->s
                $rotation_string = substr($readings['rotation'], 1, -1);    // Remove leading and trailing angle breackets
                $rot = explode(",", $rotation_string);
                $rotation = array_slice($rot, 0, 4);
                
            //###################################################################
            //# Determine if this teleporter is already known                   #
            //###################################################################
 
            // Determine if this heartbeat is from an already known Teleporter
            $sql_query = "select * from ls_os_teleport where teleport_key = :key";
            try
            {
                $stmt = $pdo->prepare($sql_query);
                $stmt->execute(['key' => $readings['key']]);
                $exists = $stmt->fetch(PDO::FETCH_ASSOC);
            }
            catch (Exception $e)
            {
                echo "FAILURE=IDENTIFY:".$e->getMessage()."\n";
            }
                    
            //###################################################################
            //# If this entry is found, then this just an update                #
            //###################################################################
            if ($exists)
            {                   
                // Get the Substitution Fields 
                $data =
                    [
                      $readings['name'],         $readings['owner'], $readings['world'],       $readings['region'],
                      $position[0],              $position[1],       $position[2],
                      $rotation[0],              $rotation[1],       $rotation[2],             $rotation[3],
                      $readings['offset'],       $readings['group'], $readings['offsetangle'],
                      $readings['locationinfo'], $readings['vernum'], $readings['localitygroup'],
                      $readings['key']
                    ];
                        
                // Create the command to run to make the update
                $sql_query  = "update ls_os_teleport set ";
                $sql_query .= "teleport_name = ?, teleport_owner_key = ?, teleport_world = ?, teleport_region = ?, ";
                $sql_query .= "teleport_region_x = ?, teleport_region_y = ?, teleport_region_z = ?, ";
                $sql_query .= "teleport_rotation_x = ?, teleport_rotation_y = ?, teleport_rotation_z = ?, teleport_rotation_s = ?, ";
                $sql_query .= "teleport_offset = ?, teleport_group_key = ?, teleport_front_offset_angle = ?, ";
                $sql_query .= "teleport_location_info = ?, teleport_version_number = ?, teleport_locality_group = ?, ";
                $sql_query .= "teleport_heartbeat = CURRENT_TIMESTAMP()";
                $sql_query .= "where teleport_key = ?";
                        
                // Attempt to Update the Database Entry for this Teleporter
                try
                {
                    $stmt = $pdo->prepare($sql_query);
                    $stmt->execute($data);
                }
                catch (Exception $e)
                {
                    echo "FAILURE=UPDATE:".$e->getMessage()."\n";
                }
            }
                
            //###################################################################
            //# If it wasn't Found, It is a new Teleporter                      #
            //###################################################################
            else
            {
                // Test to see if this new item has an name that already exists in the database.
                // Duplicate name are not permitted to prevent tue users becoming confused. If it
                // is a duplicate, send a warning that there is a name violation to the owner of
                // this new teleporter.
                
                $sql_query = "select * from ls_os_teleport where teleport_name = :name";
                try
                {
                    $stmt = $pdo->prepare($sql_query);
                    $stmt->execute(['name' => $readings['name']]);
                    $same_name = $stmt->fetch(PDO::FETCH_ASSOC);
                }
                catch (Exception $e)
                {
                    echo "FAILURE=NAME_MATCH: ".$readings['name'].":Failed with".$e->getMessage()."\n";
                }
                if ($same_name)
                {
                    echo "FAILURE=NAME_MATCH: Existing teleporter data - ";
                    echo $row['teleport_world']."/".$row['teleport_region']."/";
                    echo "<".$row['teleport_region_x'].",".$row['teleport_region_y'].",".$row['teleport_region_z'].">\n";
                }
                else
                {
                    // Get the Substitution Fields 
                    $data =
                        [
                            $readings['key'],          $readings['name'],   $readings['owner'],        $readings['world'], $readings['region'],
                            $position[0],              $position[1],        $position[2],
                            $rotation[0],              $rotation[1],        $rotation[2],              $rotation[3],
                            $readings['offset'],       $readings['group'],  $readings['offsetangle'],
                            $readings['locationinfo'], $readings['vernum'], $readings['localitygroup']
                        ];
                    
                    // Create the command to run to make the insert
                    $sql_query  = "insert into ls_os_teleport(";
                    $sql_query .= "teleport_key,           teleport_name,           teleport_owner_key,           teleport_world,       teleport_region, ";
                    $sql_query .= "teleport_region_x,      teleport_region_y,       teleport_region_z, ";
                    $sql_query .= "teleport_rotation_x,    teleport_rotation_y,     teleport_rotation_z,          teleport_rotation_s, ";
                    $sql_query .= "teleport_offset,        teleport_group_key,      teleport_front_offset_angle,";
                    $sql_query .= "teleport_location_info, teleport_version_number, teleport_locality_group";
                    $sql_query .= ")VALUES(";
                    $sql_query .= "?, ?, ?, ?, ?, ";
                    $sql_query .= "?, ?, ?, ";
                    $sql_query .= "?, ?, ?, ?, ";
                    $sql_query .= "?, ?, ?, ";
                    $sql_query .= "?, ?, ?";
                    $sql_query .= ")";
                        
                    // Attempt to Update the Database Entry for this Teleporter
                    try
                    {
                        $stmt = $pdo->prepare($sql_query);
                        $stmt->execute($data);
                    }
                    catch (Exception $e)
                    {
                        echo "FAILURE=INSERT:".$e->getMessage()."\n";
                    }
                }
            }
            
            // Send the Message Preamble 
            echo "EXTRACT_LIST=START\n";
            
            // Isolate the Individual Flags from the location information
            $this_group_flag     = $readings['locationinfo'] & $GROUP_FLAG;
            $this_region_flag    = $readings['locationinfo'] & $REGION_FLAG;
            $this_world_flag     = $readings['locationinfo'] & $WORLD_FLAG;
            $this_metaverse_flag = $readings['locationinfo'] & $METAVERSE_FLAG;
 
            $sql_query = "";
 
            // Depending on the options selected in the LOCATION_TYPES in the configuration file, this query will
            // make a selection destinations in the region holding the Teleporter. LOCAL will select all destinations
            // that have a LOCALITY_GROUP that matches the LOCALITY_GROUP value.
            $sql_query .= "select * from ls_os_teleport";
            $sql_query .= " where teleport_key != :key";
            $sql_query .= " and ((teleport_location_info & :group_flag = :this_group_flag and teleport_locality_group = :group) or teleport_location_info & :region_flag = :this_region_flag)";
            $sql_query .= " and teleport_location_info & :anon_flag = 0";
            $sql_query .= " and teleport_region = :region";         
            $sql_query .= " and teleport_world  = :world";
            $sql_query .= " and teleport_version_number != 0"; 
 
            $sql_query .= " UNION ";
 
            // Check if this s a World or Meteverse Location
            $sql_query .= "select * from ls_os_teleport ";
            $sql_query .= " where teleport_key != :key";
            $sql_query .= " and ((teleport_location_info & :world_flag = :this_world_flag and teleport_world  = :world)";
            $sql_query .= " and teleport_location_info & :anon_flag = 0";
            $sql_query .= " or (teleport_location_info & :metaverse_flag = :this_metaverse_flag and teleport_world != :world))";
            $sql_query .= " and teleport_version_number != 0";
            
            // Sort the Responses into Alphbetical Order
            $sql_query .= " order by teleport_name";
 
            $parameters = [
                    'key' => $readings['key'],
                    'group_flag' => $GROUP_FLAG,
                    'region_flag' => $REGION_FLAG,
                    'world_flag' => $WORLD_FLAG,
                    'metaverse_flag' => $METAVERSE_FLAG,
                    'anon_flag' => $ANONYMOUS_FLAG,
                    'this_group_flag' => $this_group_flag,
                    'this_region_flag' => $this_region_flag,
                    'this_world_flag' => $this_world_flag,
                    'this_metaverse_flag' => $this_metaverse_flag,
                    'group' => $readings['localitygroup'],
                    'region'=> $readings['region'],
                    'world' => $readings['world']
                      ];
            
            $this->rdSelectDestinations($sql_query, $parameters, $pdo, $readings['world'], $readings['region']);
 
            // Send the Message Postamble 
            sleep(1);
            echo "EXTRACT_LIST=END\n";
        }
 
        // If the Command is a Scan, Process the Destination Entries in the Support Database
        if ($readings['command'] == "scan")
        {
            
            //#############################################################################
            //## Scan the Contents of the Destinations for recent Heartbeats             ##
            //#############################################################################
            // Remove the Teleporter if they havw exceeded their lifetime without sending
            // a heartbeat message. Destinations that did not come from a Teleporter, that
            // manually entered are not affected by this process, but are identified as
            //being past End Of Life (EOL).
            
            $world = $readings['world'];
            
            $SqlQuery  = "select * from ls_os_teleport";
            $SqlQuery .= "where DATE_ADD(teleport_heartbeat, INTERVAL :lifetime HOUR) < CURRENT_TIMESTAMP()";
            $SqlQuery .= " and teleport_version_number != 0 ";
            if ($world != '###') $SqlQuery .= " and teleport_world = :world";
            $SqlQuery .= " order by teleport_name;";
            
            $Parameters = ['lifetime' => $readings['lifetime'] ];
            if ($world != '###') $Parameters['world'] = $world;
            
            try
            {
                $stmt = $pdo->prepare($SqlQuery);
                $stmt->execute($Parameters);
                $results = $stmt->fetchAll(PDO::FETCH_DEFAULT);
            }
            catch (Exception $e)
            {
                echo "FAILURE=SCAN:".$e->getMessage()."\n";
            }
            
            //#########################################################################################
            //# Process Each Line                                                                     #
            //#########################################################################################
            
            echo "SCAN_LIST=START\n";
            echo "//=========================== Date: ".date("Y-m-d H:i:s")."==================\n";
            
            foreach ($results as $row)
            {
                $action_string = "SCANNED";
                $teleport_name = $row['teleport_name'];
                $teleport_version = $row['teleport_version_number'];
                
                // If OnlyScn is FALSE, delete the teleporter from the teleporter table
                if ($readings['onlyscan'] == 0)
                {
                    $sql_query1 = "delete from ls_os_teleport where teleport_key = :key";
                    $parameters1 = ['key' => $row['teleport_key'] ];
                    $stmt1 = $pdo->prepare($sql_query1);
                    $stmt1->execute($parameters1);
                    $results1 = $stmt1->fetchAll(PDO::FETCH_DEFAULT);
                    $action_string = "DELETED";
                } 
                echo $row['teleport_name']."|".$action_string."|";
                echo "hop://".$row['teleport_world']."/".$row['teleport_region']."/".$row['teleport_region_x']."/".$row['teleport_region_y']."/".$row['teleport_region_z']."\n";
            }
            echo "SCAN_LIST=END\n";
        }
    }

References $parameters, $readings, rdConfirmUser(), rdOpenDatabase(), and rdSelectDestinations().

Here is the call graph for this function:

rdSelectDestinations()

rdTeleport::rdSelectDestinations	(		$SqlQuery,
			$Parameters,
			$Pdo,
			$ThisWorld,
			$ThisRegion )

Print out the selected teleporters for the Destination Notecard.

Parameters

$SqlQuery	The SQL Query to select the Teleporters
$Parameters	The Parameters to inser into the SQL Query
$Pdo	The Database instance to use to access the Database
$ThisWorld	The address of the world the Script is in
$ThisRegion	The name of the region this SCript is in

This routine extracts the selected entries for the ls_os_teleport table, formats the data and send it out for return to teh calling OPen Simulator script.

Definition at line 44 of file teleport.php.

    {
        try
        {
            $stmt = $Pdo->prepare($SqlQuery);
            $stmt->execute($Parameters);
            $results = $stmt->fetchAll(PDO::FETCH_DEFAULT);
 
            //#########################################################################################
            //# Process Each Line                                                                     #
            //#########################################################################################
            
            if ($results)
            {
                    
                foreach ($results as $row)
                {
                    $result_world = $row['teleport_world']; $result_region = $row['teleport_region'];
                    
                    echo $row['teleport_name']."|";
                    echo "<".$row['teleport_region_x'].",".$row['teleport_region_y'].",".$row['teleport_region_z'].">|";
                    echo "<".$row['teleport_rotation_x'].",".$row['teleport_rotation_y'].",".$row['teleport_rotation_z'].",".$row['teleport_rotation_s'].">|";
                    echo "<".$row['teleport_offset'].",".$row['teleport_front_offset_angle'].",".$row['teleport_location_info'].">|";
                    echo $row['teleport_locality_group']."|";
                    
                    // Check if the Full Address is Needed
                    if ($result_world != $ThisWorld)
                    {
                        $location_type = 2;
                        echo $location_type."|";
                        echo $result_region."|".$result_world."\n";
                    }
                    else if ($result_region != $ThisRegion)
                    {
                        $location_type = 1;
                        echo $location_type."|";
                        echo $result_region."\n";
                    }
                    else
                    {
                        $location_type = 0;
                        echo $location_type."\n";
                    }
                }
            }
        }
        catch (Exception $e)
        {
            echo("FAILURE=EXTRACT:".$e->getMessage()."\n");
        }
    }

Referenced by rdProcessTeleport().

Here is the caller graph for this function:

---

The documentation for this class was generated from the following file:

• teleport.php