My first step to contributing

[abdi]

Hello Till,

Let this be my first thread to understanding ISPConfig3 code structure so that I can contribute. My first contribution is add a new API function for downloading and restoring of backup files through API.

Please help as much as possible in this thread to achieve that goal. Then I can hit more complex functions.

Will keep you updated along the way ..

Joseph

[abdi]

Hello Till,

Here is the backup download / restore API function. I have tested it and it works. You may however advice on the code formats and if any suggestions especially in the area of reporting errors.

	//* Backup download and restoration by Abdi Joseph
	public function sites_web_domain_backup($session_id, $backup_id, $params)
    {
		global $app;
		
		//*Set variables
		$action_type	=	$params['action_type'];		
		$backup_record 	= 	$app->db->queryOneRecord("SELECT * FROM `web_backup` WHERE `backup_id`='$backup_id'");		
		$server_id		=	$backup_record['server_id'];

		//*Set default action state
		$action_state	=	"pending";		
		$tstamp			=	time();
		
		//* Basic validation of variables
		if ($server_id <= 0) return "Invalid or non existant backup_id $backup_id";
		if ($action_type != 'backup_download' and $action_type != 'backup_restore') return "Invalid action_type $action_type";
		
		//* Validate instance
		$instance_record	=	$app->db->queryOneRecord("SELECT * FROM `sys_remoteaction` WHERE `action_param`='$backup_id' and `action_type`='$action_type' and `action_state`='pending'");	
		if ($instance_record['action_id'] >= 1) return "There is already a pending $action_type action";
		
		//* Save the record
		if ($app->db->query("INSERT INTO `sys_remoteaction` SET 
			`server_id`		=	'$server_id',
			`tstamp`		=	'$tstamp',
 	 		`action_type`	=	'$action_type',
 	 		`action_param`	=	'$backup_id',
			`action_state`	=	'$action_state'")) return true;
		else return false;
	}

To test drive it you can use the following:

try 
{ 
	$session_id = $client->login($username,$password);
	
	//* Set the function parameters.
	$backup_id 		= 	2;
	$action_type	=	"backup_restore";
	$params = array(
			'action_type' 	=> $action_type
			);
	
	print_r($client->sites_web_domain_backup($session_id, $backup_id, $params));
} catch (SoapFault $e) { echo $client->__getLastResponse(); die('SOAP Error: '.$e->getMessage()); }

If everything is fine, let me so that I can work on the documentation as well ...

I will attach the finel remoting.inc.php file on your approval.

[till]

The function is generally fine, just a few minor things:

- The permission check is missing.
- Errors are not returned as soap faults.
- The params array contains only one value if I see it correctly, you should use $action as parameter and not $params array.

About the syntax, please use { ... } in if / else statements.

Here my proposed changes (untested):

//* Backup download and restoration by Abdi Joseph
	public function sites_web_domain_backup($session_id, $backup_id, $action_type)
    {
		global $app;
		
		if(!$this->checkPerm($session_id, 'sites_web_domain_update')) {
			$this->server->fault('permission_denied', 'You do not have the permissions to access this function.');
			return false;
		}
		
		//*Set variables	
		$backup_record 	= 	$app->db->queryOneRecord("SELECT * FROM `web_backup` WHERE `backup_id`='$backup_id'");		
		$server_id		=	$backup_record['server_id'];

		//*Set default action state
		$action_state	=	"pending";		
		$tstamp			=	time();
		
		//* Basic validation of variables
		if ($server_id <= 0) {
		    $this->server->fault('invalid_backup_id', "Invalid or non existant backup_id $backup_id");
            return false;
		}

		if ($action_type != 'backup_download' and $action_type != 'backup_restore') {
		   $this->server->fault('invalid_action', "Invalid action_type $action_type");
            return false;
		}

		//* Validate instance
		$instance_record	=	$app->db->queryOneRecord("SELECT * FROM `sys_remoteaction` WHERE `action_param`='$backup_id' and `action_type`='$action_type' and `action_state`='pending'");	
		if ($instance_record['action_id'] >= 1) {
		    $this->server->fault('duplicate_action', "There is already a pending $action_type action");
            return false;
		}
		
		//* Save the record
		if ($app->db->query("INSERT INTO `sys_remoteaction` SET 
			`server_id`		=	'$server_id',
			`tstamp`		=	'$tstamp',
 	 		`action_type`	=	'$action_type',
 	 		`action_param`	=	'$backup_id',
			`action_state`	=	'$action_state'")) {
			    return true;
		} else {
		    return false;
		}
	}

[abdi]

Thanks for that information Till,

I have made the changes accordingly and tested it and yes it works fine!

What is the way forward in this regard now to have this function added to the future versions?

First I guess I need to prepare the API documenation and example file, right?

Joseph

[abdi]

Hello Till,

Please find attached my entire changes ...
The attachment includes:

1. /interface/lib/classes/remoting.inc
2. API documentation (sites_web_domain_backup.html)
3. API navigation file (navigation.html)
4. API example file (sites_web_domain_backup.php)

I have tested these API changes on my production server and everything works fine.

I just made a slight change to the proposed code though:

Instead of return true, I changed to return SUCCESS
and Instead of return false, I changed to return FAIL

Let me know if there any comments or suggestions ..

Joseph

[till]

Thanks for your contribution. I've added it to the bugtracker as proposed for inclusion.

Instead of return true, I changed to return SUCCESS
and Instead of return false, I changed to return FAIL

Thats inconsistent with the other api functions, so I will have to change that to true/false before we can include your code.

[abdi]

Hello Till,

Please find attached ALL new changes applied with return being to TRUE and FALSE.

Changes include in

1. remoting.inc.php
2. sites_web_domain_backup.html (API documentation file)
3. sites_web_domain_backup.php (API example file)

Joseph