teleport.php File Reference

Interface between Open Simulator and SQL Database via HTML. More...

Go to the source code of this file.

Functions
	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.

Variables
	$parameters = json_encode($_GET)
	$readings = json_decode( $parameters, true )
	$my_teleport = new rdTeleport()

Detailed Description

Interface between Open Simulator and SQL Database via HTML.

Author

River Drifter river.nosp@m.-dri.nosp@m.fter@.nosp@m.auss.nosp@m.iebro.nosp@m.adba.nosp@m.nd.co.nosp@m.m.au

Copyright

Software: GNU General Public License v3.0 or later https://spdx.org/licenses/GPL-3.0-or-later.html

Documentation: Creative Commons Attribution Share Alike 4.0 International https://spdx.org/licenses/CC-BY-SA-4.0.html

Version

2.2.0

Date

05-January-2026

This script is used to receive commands from the Open Simulator scripts used to control a Teleportation device. The script is triggered by receiving a command from the Open Simulator object running the teleporter(s).

The primary command processed by this script is the "heartbeat" command. This is used to record that the teleporter is still active and should not be remoed as being inoperative. The heartbeat command is also used to update the location and orientation of the teleporter. It will also add new telporters to the database provided that it can be adequately recognised.

Definition in file teleport.php.

Function Documentation

rdConfirmUser()

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 42 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()

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 99 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()

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 142 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';
                
        $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(), and rdOpenDatabase().

Here is the call graph for this function:

Variable Documentation

$my_teleport

$my_teleport = new rdTeleport()

Definition at line 474 of file teleport.php.

$parameters

$parameters = json_encode($_GET)

Definition at line 471 of file teleport.php.

Referenced by rdProcessTeleport().

$readings

$readings = json_decode( $parameters, true )

Definition at line 472 of file teleport.php.

Referenced by rdConfirmUser(), and rdProcessTeleport().