raspisms/adapters/AdapterInterface.php

145 lines
4.9 KiB
PHP
Raw Normal View History

2019-11-11 21:01:40 +01:00
<?php
2020-01-17 18:19:25 +01:00
/*
* This file is part of RaspiSMS.
*
* (c) Pierre-Lin Bonnemaison <plebwebsas@gmail.com>
*
* This source file is subject to the GPL-3.0 license that is bundled
* with this source code in the file LICENSE.
*/
namespace adapters;
2019-11-11 21:01:40 +01:00
/**
* Interface for phones adapters
* Phone's adapters allow RaspiSMS to use a platform to communicate with a phone number.
* Its an adapter between internal and external code, as an API, command line software, physical modem, etc.
*
* All Phone Adapters must implement this interface
*/
interface AdapterInterface
{
2019-11-12 05:18:32 +01:00
/**
2020-01-17 18:19:25 +01:00
* Adapter constructor, called when instanciated by RaspiSMS.
*
* @param json string $datas : JSON string of the datas to configure interaction with the implemented service
2019-11-12 05:18:32 +01:00
*/
public function __construct(string $datas);
2020-01-17 18:19:25 +01:00
/**
* Classname of the adapter.
*/
public static function meta_classname(): string;
/**
* Uniq name of the adapter
* It should be the classname of the adapter un snakecase
*/
public static function meta_uid() : string;
2019-11-12 05:18:32 +01:00
2019-11-11 21:01:40 +01:00
/**
* Name of the adapter.
2020-01-17 18:19:25 +01:00
* It should probably be the name of the service it adapt (e.g : Gammu SMSD, OVH SMS, SIM800L, etc.).
2019-11-11 21:01:40 +01:00
*/
2020-01-17 18:19:25 +01:00
public static function meta_name(): string;
2019-11-11 21:01:40 +01:00
/**
* Description of the adapter.
* A short description of the service the adapter implements.
*/
2020-01-17 18:19:25 +01:00
public static function meta_description(): string;
/**
2020-01-17 18:19:25 +01:00
* List of entries we want in datas for the adapter.
*
* @return array : Eachline line is a field as an array with keys : name, title, description, required
*/
2020-01-17 18:19:25 +01:00
public static function meta_datas_fields(): array;
2019-11-11 21:01:40 +01:00
/**
* Does the implemented service support reading smss.
*/
public static function meta_support_read(): bool;
2019-11-11 21:01:40 +01:00
/**
2020-01-17 18:19:25 +01:00
* Does the implemented service support flash smss.
2019-11-11 21:01:40 +01:00
*/
2020-01-17 18:19:25 +01:00
public static function meta_support_flash(): bool;
2019-11-11 21:01:40 +01:00
/**
* Does the implemented service support status change callback.
2019-11-11 21:01:40 +01:00
*/
2020-01-17 18:19:25 +01:00
public static function meta_support_status_change(): bool;
2020-04-02 18:40:53 +02:00
/**
* Does the implemented service support reception callback.
*/
public static function meta_support_reception(): bool;
2020-01-17 18:19:25 +01:00
2019-11-11 21:01:40 +01:00
/**
2020-01-17 18:19:25 +01:00
* Method called to send a SMS to a number.
*
2019-11-11 21:01:40 +01:00
* @param string $destination : Phone number to send the sms to
2020-01-17 18:19:25 +01:00
* @param string $text : Text of the SMS to send
* @param bool $flash : Is the SMS a Flash SMS
*
* @return array : [
* bool 'error' => false if no error, true else
* ?string 'error_message' => null if no error, else error message
* array 'uid' => Uid of the sms created on success
* ]
2019-11-11 21:01:40 +01:00
*/
2020-01-17 18:19:25 +01:00
public function send(string $destination, string $text, bool $flash = false);
2019-11-11 21:01:40 +01:00
/**
* Method called to read SMSs of the number.
2020-01-17 18:19:25 +01:00
*
* @return array : [
* bool 'error' => false if no error, true else
* ?string 'error_message' => null if no error, else error message
* array 'smss' => Array of the sms reads
* [
* [
* string 'at' => sms reception date,
* string 'text' => sms text,
* string 'origin' => phone number who sent the sms
* ],
* ...
* ]
* ]
2019-11-11 21:01:40 +01:00
*/
2020-01-17 18:19:25 +01:00
public function read(): array;
/**
* Method called to verify if the adapter is working correctly
2020-01-17 18:19:25 +01:00
* should be use for exemple to verify that credentials and number are both valid.
*
* @return bool : False on error, true else
*/
2020-01-17 18:19:25 +01:00
public function test(): bool;
/**
2020-01-17 18:19:25 +01:00
* Method called on reception of a status update notification for a SMS.
*
* @return mixed : False on error, else array ['uid' => uid of the sms, 'status' => New status of the sms (\models\Sended::STATUS_UNKNOWN, \models\Sended::STATUS_DELIVERED, \models\Sended::STATUS_FAILED)]
*/
2020-01-17 18:19:25 +01:00
public static function status_change_callback();
2020-04-02 18:40:53 +02:00
/**
* Method called on reception of a sms notification.
*
* @return array : [
* bool 'error' => false on success, true on error
* ?string 'error_message' => null on success, error message else
* array 'sms' => array [
* string 'at' : Recepetion date format Y-m-d H:i:s,
* string 'text' : SMS body,
* string 'origin' : SMS sender,
* ]
*
* ]
*/
public static function reception_callback() : array;
2019-11-11 21:01:40 +01:00
}