updating to FRITZ!OS 7.50 new services; code review; minor optimizati…

…ons and improvements; updating READ.ME

.gitignore

@@ -1,7 +1,8 @@
 /generator.php
 /composer.lock
-/test.php
+/tester.php
 /auto/
 /vendor/
 /src/classgenerator.php
 /docs/auraSCPD.docx
+/legacy

README.md

@@ -28,7 +28,7 @@ $callList = $fritzbox->getCallList();
 
 That´s all! **Simple, convenient, straightforward!**
 
-The file `fritzsoap.php` is the meta class providing general basic objects. All other files are subclasses as descendants of this meta class.
+The file `fritzsoap.php` is the meta class providing general basic objects. All other files are subclasses as descendants of this meta class. The **direct instantiation of fritzsoap leads to an error**.
 
 ### Classes and methods
 
@@ -148,17 +148,17 @@ In all other cases you will find a link like this:
 There is one exception so far: `AURA`. Through a [thread in the IP Phone Forum](https://www.ip-phone-forum.de/threads/v0-4-1-30-09-2009-fritzboxnet-net-bibliothek-f%C3%BCr-fritz-box.190718/) I learned how this service works. The six actions of this service are coded and an [unofficial documentation](docs/auraSCPD.pdf) can be found in the `/docs` folder.
 You must have activated the USB remote access function in the FRITZ!Box to be able to access this service!
 
-#### Control
-
-The group of ghosts includes the `Control` services, of which I found seven with different serviceType and controlURL. The services are therefore mapped accordingly in the classes **Control_1** to **Control_7**.
+#### Some other ghosts
 
-#### Other ghosts
-
-* `any` (has no actions - generic template?)
+* `any` has no actions - generic template?
 * `avmnexus`
-* `fritzbox` (with FRITZ!OS 7.25 no longer existend in the description XML but recently still available here)
+* `fritzbox` disappeared with FRITZ!OS 7.29 (or before?) but reappeared with 7.50
 * `l2tpv3`
 
+#### Control
+
+Up to and including FRITZ!OS 7.29 there was a group of `Control` services of the same name, of which I found seven with different serviceType and controlURL. The services are therefore mapped accordingly in the classes **Control_1** to **Control_7**. With FRITZ!OS 7.50 no longer included in the description files, I keep them here for the sake of completeness.
+
 ## Requirements
 
 * PHP 7.3 or higher
@@ -170,7 +170,7 @@ You can install it through Composer:
 
 ```js
 "require": {
-    "blacksenator/fritzsoap": "^2.4"
+    "blacksenator/fritzsoap": "^2.8"
 },
 ```
 
@@ -184,13 +184,20 @@ git clone https://github.com/blacksenator/fritzsoap.git
 
 ### Authentication
 
-There are a number of services that could be called as UPnP even without credentials. For reasons of simplification, no distinction was made in the constructor of the respective classes.
+There are a few services (IDG-related) that can be called without credentials:
+
+* WANCommonIFC1
+* WANDSLLinkC1
+* WANIPConn1
+* WANIPv6Firewall1
+
+All others require the specification of the FRITZ!Box URL, user and password.
 
 ### Examples
 
 Below are a few examples of how the provided actions or additional functions can be called:
 
-If you wanna get a file with the available services of your FRITZ!Box or FRITZ!Repeater:
+If you wanna get a file with all the available services of your FRITZ!Box or FRITZ!Repeater:
 
 ```PHP
 require_once('vendor/autoload.php');
@@ -202,12 +209,12 @@ $services = $fritzbox->getServiceDescription();
 $services->asXML('services.xml');
 ```
 
-**Hint:** The function `getServiceDescription()` is available in all classes due to inheritance!
-You can also get a more detailed structure with `getServiceDescription(true)`. In this case, the information from the FRITZ!Box is gathered again and all parameters of the actions are also output, as well as the file name of the XML from which the information originates.
+**Hint:** The function `getServiceDescription()` is available in all classes due to inheritance and available without any credentials and provides a good overview! You can also get a more detailed structure with `getServiceDescription(true)`. In this case all parameters of the actions are also output, as well as the file name of the XML from which the information originates.
 
 Example output (clipping):
 ![alt text](assets/detail_xml.jpg "details about services and actions")
 
+But now some more practical applications:
 Example to get a list of all your network devices:
 
 ```PHP

src/AdressTrait.php

@@ -0,0 +1,66 @@
+<?php
+
+namespace blacksenator\fritzsoap;
+
+/**
+ * This trait provides basic functions to adress the FRITZ!Box properly
+ *
+ * Copyright (c) 2023 Volker Püschel
+ * @license MIT
+ */
+
+use blacksenator\fbvalidateurl\fbvalidateurl;
+
+trait AdressTrait
+{
+    /**
+     * sets the adresses fo the FRITZ!Box resources to access descritions (XML)
+     * aswell as SOAP interfaces (services and actions)
+     *
+     * @param string $url
+     * @return void
+     */
+    protected function setResourceAdresses(string $url)
+    {
+        $validator = new fbvalidateurl;
+        $this->url = $validator->getValidURL($url);
+        $this->assembleServerAdress();
+    }
+
+    /**
+     * assemble the correct server address, depending on whether it is encrypted
+     * or not
+     *
+     * @return void
+     */
+    private function assembleServerAdress()
+    {
+        if ($this->url['scheme'] == 'http') {
+            $this->fritzBoxURL = 'http://' . $this->url['host'] . ':' . self::HTTP_PORT;
+        } elseif ($this->url['scheme'] == 'https') {
+            $this->fritzBoxURL = 'https://' . $this->url['host'] . ':' . self::HTTPS_PORT;
+        } else {
+            throw new \Exception ('Could not assemble valid server address!');
+        }
+    }
+
+        /**
+     * get the validated URL parameters
+     *
+     * @return array
+     */
+    public function getURL(): array
+    {
+        return $this->url;
+    }
+
+    /**
+     * get the server adress
+     *
+     * @return string
+     */
+    public function getServerAdress(): string
+    {
+        return $this->fritzBoxURL;
+    }
+}

src/Control_1.php

@@ -5,7 +5,8 @@
 /**
  * The class provides functions to read and manipulate data via TR-064 interface
  * on FRITZ!Box router from AVM.
- * No specific documentation available!
+ * No specific documentation available! As of FRITZ!OS 7.50, control services
+ * can no longer be found in the description files
  *
  * @see: https://avm.de/service/schnittstellen/
  *
@@ -89,7 +90,7 @@ public function getCurrentConnectionInfo($connectionID)
         $result = $this->client->GetCurrentConnectionInfo(
             new \SoapParam($connectionID, 'ConnectionID'));
         if ($this->errorHandling($result, 'Could not ... from/to FRITZ!Box')) {
-            return null;
+            return;
         }
 
         return $result;

src/Control_2.php

@@ -5,7 +5,8 @@
 /**
  * The class provides functions to read and manipulate data via TR-064 interface
  * on FRITZ!Box router from AVM.
- * No specific documentation available!
+ * No specific documentation available! As of FRITZ!OS 7.50, control services
+ * can no longer be found in the description files
  *
  * @see: https://avm.de/service/schnittstellen/
  *
@@ -119,7 +120,7 @@ public function browse($objectID, $browseFlag, $filter, $startingIndex, $request
             new \SoapParam($requestedCount, 'RequestedCount'),
             new \SoapParam($sortCriteria, 'SortCriteria'));
         if ($this->errorHandling($result, 'Could not ... from/to FRITZ!Box')) {
-            return null;
+            return;
         }
 
         return $result;
@@ -159,7 +160,7 @@ public function search($containerID, $searchCriteria, $filter, $startingIndex, $
             new \SoapParam($requestedCount, 'RequestedCount'),
             new \SoapParam($sortCriteria, 'SortCriteria'));
         if ($this->errorHandling($result, 'Could not ... from/to FRITZ!Box')) {
-            return null;
+            return;
         }
 
         return $result;

src/Control_3.php

@@ -5,7 +5,8 @@
 /**
  * The class provides functions to read and manipulate data via TR-064 interface
  * on FRITZ!Box router from AVM.
- * No specific documentation available!
+ * No specific documentation available! As of FRITZ!OS 7.50, control services
+ * can no longer be found in the description files
  *
  * @see: https://avm.de/service/schnittstellen/
  *

src/Control_4.php

@@ -5,7 +5,8 @@
 /**
  * The class provides functions to read and manipulate data via TR-064 interface
  * on FRITZ!Box router from AVM.
- * No specific documentation available!
+ * No specific documentation available! As of FRITZ!OS 7.50, control services
+ * can no longer be found in the description files
  *
  * @see: https://avm.de/service/schnittstellen/
  *
@@ -44,7 +45,7 @@ public function isAuthorized($deviceID)
         $result = $this->client->IsAuthorized(
             new \SoapParam($deviceID, 'DeviceID'));
         if ($this->errorHandling($result, 'Could not ... from/to FRITZ!Box')) {
-            return null;
+            return;
         }
 
         return $result;
@@ -66,7 +67,7 @@ public function isValidated($deviceID)
         $result = $this->client->IsValidated(
             new \SoapParam($deviceID, 'DeviceID'));
         if ($this->errorHandling($result, 'Could not ... from/to FRITZ!Box')) {
-            return null;
+            return;
         }
 
         return $result;

src/Control_5.php

@@ -5,7 +5,8 @@
 /**
  * The class provides functions to read and manipulate data via TR-064 interface
  * on FRITZ!Box router from AVM.
- * No specific documentation available!
+ * No specific documentation available! As of FRITZ!OS 7.50, control services
+ * can no longer be found in the description files
  *
  * @see: https://avm.de/service/schnittstellen/
  *
@@ -89,7 +90,7 @@ public function getCurrentConnectionInfo($connectionID)
         $result = $this->client->GetCurrentConnectionInfo(
             new \SoapParam($connectionID, 'ConnectionID'));
         if ($this->errorHandling($result, 'Could not ... from/to FRITZ!Box')) {
-            return null;
+            return;
         }
 
         return $result;

src/Control_6.php

@@ -5,7 +5,8 @@
 /**
  * The class provides functions to read and manipulate data via TR-064 interface
  * on FRITZ!Box router from AVM.
- * No specific documentation available!
+ * No specific documentation available! As of FRITZ!OS 7.50, control services
+ * can no longer be found in the description files
  *
  * @see: https://avm.de/service/schnittstellen/
  *
@@ -119,7 +120,7 @@ public function browse($objectID, $browseFlag, $filter, $startingIndex, $request
             new \SoapParam($requestedCount, 'RequestedCount'),
             new \SoapParam($sortCriteria, 'SortCriteria'));
         if ($this->errorHandling($result, 'Could not ... from/to FRITZ!Box')) {
-            return null;
+            return;
         }
 
         return $result;
@@ -159,7 +160,7 @@ public function search($containerID, $searchCriteria, $filter, $startingIndex, $
             new \SoapParam($requestedCount, 'RequestedCount'),
             new \SoapParam($sortCriteria, 'SortCriteria'));
         if ($this->errorHandling($result, 'Could not ... from/to FRITZ!Box')) {
-            return null;
+            return;
         }
 
         return $result;

src/Control_7.php

@@ -5,7 +5,8 @@
 /**
  * The class provides functions to read and manipulate data via TR-064 interface
  * on FRITZ!Box router from AVM.
- * No specific documentation available!
+ * No specific documentation available! As of FRITZ!OS 7.50, control services
+ * can no longer be found in the description files
  *
  * @see: https://avm.de/service/schnittstellen/
  *
@@ -44,7 +45,7 @@ public function isAuthorized($deviceID)
         $result = $this->client->IsAuthorized(
             new \SoapParam($deviceID, 'DeviceID'));
         if ($this->errorHandling($result, 'Could not ... from/to FRITZ!Box')) {
-            return null;
+            return;
         }
 
         return $result;
@@ -66,7 +67,7 @@ public function isValidated($deviceID)
         $result = $this->client->IsValidated(
             new \SoapParam($deviceID, 'DeviceID'));
         if ($this->errorHandling($result, 'Could not ... from/to FRITZ!Box')) {
-            return null;
+            return;
         }
 
         return $result;

src/WANDSLLinkC1_1.php

@@ -42,7 +42,7 @@ public function setDSLLinkType($linkType)
         $result = $this->client->SetDSLLinkType(
             new \SoapParam($linkType, 'NewLinkType'));
         if ($this->errorHandling($result, 'Could not ... from/to FRITZ!Box')) {
-            return null;
+            return;
         }
 
         return $result;
@@ -121,7 +121,7 @@ public function setDestinationAddress($destinationAddress)
         $result = $this->client->SetDestinationAddress(
             new \SoapParam($destinationAddress, 'NewDestinationAddress'));
         if ($this->errorHandling($result, 'Could not ... from/to FRITZ!Box')) {
-            return null;
+            return;
         }
 
         return $result;
@@ -161,7 +161,7 @@ public function setATMEncapsulation($aTMEncapsulation)
         $result = $this->client->SetATMEncapsulation(
             new \SoapParam($aTMEncapsulation, 'NewATMEncapsulation'));
         if ($this->errorHandling($result, 'Could not ... from/to FRITZ!Box')) {
-            return null;
+            return;
         }
 
         return $result;
@@ -201,7 +201,7 @@ public function setFCSPreserved($fCSPreserved)
         $result = $this->client->SetFCSPreserved(
             new \SoapParam($fCSPreserved, 'NewFCSPreserved'));
         if ($this->errorHandling($result, 'Could not ... from/to FRITZ!Box')) {
-            return null;
+            return;
         }
 
         return $result;

src/WANDSLLinkC1_2.php

@@ -42,7 +42,7 @@ public function setDSLLinkType($linkType)
         $result = $this->client->SetDSLLinkType(
             new \SoapParam($linkType, 'NewLinkType'));
         if ($this->errorHandling($result, 'Could not ... from/to FRITZ!Box')) {
-            return null;
+            return;
         }
 
         return $result;
@@ -121,7 +121,7 @@ public function setDestinationAddress($destinationAddress)
         $result = $this->client->SetDestinationAddress(
             new \SoapParam($destinationAddress, 'NewDestinationAddress'));
         if ($this->errorHandling($result, 'Could not ... from/to FRITZ!Box')) {
-            return null;
+            return;
         }
 
         return $result;
@@ -161,7 +161,7 @@ public function setATMEncapsulation($aTMEncapsulation)
         $result = $this->client->SetATMEncapsulation(
             new \SoapParam($aTMEncapsulation, 'NewATMEncapsulation'));
         if ($this->errorHandling($result, 'Could not ... from/to FRITZ!Box')) {
-            return null;
+            return;
         }
 
         return $result;
@@ -201,7 +201,7 @@ public function setFCSPreserved($fCSPreserved)
         $result = $this->client->SetFCSPreserved(
             new \SoapParam($fCSPreserved, 'NewFCSPreserved'));
         if ($this->errorHandling($result, 'Could not ... from/to FRITZ!Box')) {
-            return null;
+            return;
         }
 
         return $result;