Merge pull request #11 from 123inkt/get_attributes_operation

Add GetPrinterAttributesOperation

Add a function to get printer attributes, Implement several parsing functions to allow correct parsing of these attributes.
Adds two new protocol entities; for Collections and Resolution
Refactors the Ipp response parsing to maintain readability

Author: RubenKluft

README.md

@@ -63,6 +63,16 @@ composer require digitalrevolution/ipp
     $ipp->printerAdministration()->deletePrinter($printer);
 ```
 
+### Get Printer attributes
+```php
+    $printer = new IppPrinter();
+    $printer->setHostname('my.printer');
+
+    $response = $ipp->getPrinterAttributes($printer);
+    $attributes = $response->getAttributes();
+    $printerName = $attributes["printer-name"]->getValue();
+```
+
 ### Creating a custom IPP operation
 
 This project is created to be easily extensible, adding a new IPP operation is as simple as making sure it has an identifier in IppOperationEnum  

src/Entity/Response/CupsIppResponse.php

@@ -13,7 +13,7 @@
 class CupsIppResponse implements IppResponseInterface
 {
     /**
-     * @param IppAttribute[] $attributes
+     * @param array<string, IppAttribute> $attributes
      */
     public function __construct(private readonly IppStatusCodeEnum $statusCode, private readonly array $attributes)
     {
@@ -57,7 +57,7 @@ public function getStatusMessage(): ?string
     }
 
     /**
-     * @return IppAttribute[]
+     * @inheritDoc
      */
     public function getAttributes(): array
     {

src/Entity/Response/IppResponseInterface.php

@@ -5,6 +5,7 @@
 namespace DR\Ipp\Entity\Response;
 
 use DR\Ipp\Enum\JobStateEnum;
+use DR\Ipp\Protocol\IppAttribute;
 
 interface IppResponseInterface
 {
@@ -13,4 +14,9 @@ public function getJobUri(): ?string;
     public function getJobState(): ?JobStateEnum;
 
     public function getStatusMessage(): ?string;
+
+    /**
+     * @return array<string, IppAttribute>
+     */
+    public function getAttributes(): array;
 }

src/Enum/IppTypeEnum.php

@@ -6,6 +6,13 @@
 
 enum IppTypeEnum: int
 {
+    case Unsupported = 0x10;
+    case Default = 0x11;
+    case Unknown = 0x12;
+    case NoValue = 0x13;
+    case NotSettable = 0x15;
+    case DeleteAttribute = 0x16;
+    case AdminDefine = 0x17;
     case Int = 0x21;
     case Bool = 0x22;
     case Enum = 0x23;

src/Ipp.php

@@ -14,6 +14,7 @@
 use DR\Ipp\Operations\Cups\CupsCreatePrinter;
 use DR\Ipp\Operations\Cups\CupsDeletePrinter;
 use DR\Ipp\Operations\GetJobAttributesOperation;
+use DR\Ipp\Operations\GetPrinterAttributesOperation;
 use DR\Ipp\Operations\PrintOperation;
 use DR\Ipp\Protocol\IppResponseParser;
 use DR\Ipp\Service\PrinterAdminService;
@@ -31,6 +32,7 @@ class Ipp implements LoggerAwareInterface
 
     private ?PrintOperation $printOperation = null;
     private ?GetJobAttributesOperation $getJobAttributes = null;
+    private ?GetPrinterAttributesOperation $getPrinterAttributes = null;
 
     private ?PrinterAdminService $printerAdmin = null;
 
@@ -72,4 +74,15 @@ public function getJobAttributes(string $jobUri): IppResponseInterface
 
         return $this->getJobAttributes->getJob($jobUri);
     }
+
+    /**
+     * Requests a list of printer attributes for the specified printer
+     * @throws ClientExceptionInterface
+     */
+    public function getPrinterAttributes(IppPrinter $printer): IppResponseInterface
+    {
+        $this->getPrinterAttributes ??= new GetPrinterAttributesOperation($this->server, $this->httpClient);
+
+        return $this->getPrinterAttributes->getAttributes($printer);
+    }
 }

src/Operations/GetPrinterAttributesOperation.php

@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+namespace DR\Ipp\Operations;
+
+use DR\Ipp\Client\IppHttpClientInterface;
+use DR\Ipp\Entity\IppPrinter;
+use DR\Ipp\Entity\IppServer;
+use DR\Ipp\Entity\Response\IppResponseInterface;
+use DR\Ipp\Enum\IppOperationEnum;
+use DR\Ipp\Enum\IppTypeEnum;
+use DR\Ipp\Protocol\IppAttribute;
+use DR\Ipp\Protocol\IppOperation;
+use Psr\Http\Client\ClientExceptionInterface;
+
+/**
+ * @internal
+ */
+class GetPrinterAttributesOperation
+{
+    public function __construct(private readonly IppServer $server, private readonly IppHttpClientInterface $client)
+    {
+    }
+
+    /**
+     * @throws ClientExceptionInterface
+     */
+    public function getAttributes(IppPrinter $printer): IppResponseInterface
+    {
+        $printerUri = $this->server->getUri() . '/printers/' . $printer->getHostname();
+
+        $operation = new IppOperation(IppOperationEnum::GetPrinterAttributes);
+        $operation->addOperationAttribute(new IppAttribute(IppTypeEnum::Charset, 'attributes-charset', 'utf-8'));
+        $operation->addOperationAttribute(new IppAttribute(IppTypeEnum::NaturalLanguage, 'attributes-natural-language', 'en'));
+        $operation->addOperationAttribute(new IppAttribute(IppTypeEnum::Uri, 'printer-uri', $printerUri));
+        $operation->addOperationAttribute(new IppAttribute(IppTypeEnum::Keyword, 'requested-attributes', 'all'));
+
+        return $this->client->sendRequest($operation);
+    }
+}

src/Protocol/IppAttribute.php

@@ -28,6 +28,16 @@ public function getValue(): mixed
         return $this->value;
     }
 
+    public function appendValue(mixed $additionalValue): self
+    {
+        if (is_array($this->value) === false) {
+            $values = [$this->value];
+        }
+        $values[] = $additionalValue;
+
+        return new self($this->type, $this->name, $values);
+    }
+
     /**
      * @internal
      */

src/Protocol/IppCollection.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace DR\Ipp\Protocol;
+
+class IppCollection
+{
+    /** @var array<string, mixed> */
+    private array $values = [];
+
+    public function add(string $name, mixed $value): void
+    {
+        $this->values[$name] = $value;
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function getValues(): array
+    {
+        return $this->values;
+    }
+}

src/Protocol/IppResolution.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace DR\Ipp\Protocol;
+
+class IppResolution
+{
+    public function __construct(private readonly int $crossFeedResolution, private readonly int $feedResolution, private readonly int $unit)
+    {
+    }
+
+    public function getCrossFeedResolution(): int
+    {
+        return $this->crossFeedResolution;
+    }
+
+    public function getFeedResolution(): int
+    {
+        return $this->feedResolution;
+    }
+
+    public function getUnit(): int
+    {
+        return $this->unit;
+    }
+}

src/Protocol/IppResponseParser.php

@@ -4,40 +4,45 @@
 
 namespace DR\Ipp\Protocol;
 
-use DateTime;
 use DR\Ipp\Entity\Response\CupsIppResponse;
 use DR\Ipp\Entity\Response\IppResponseInterface;
 use DR\Ipp\Enum\IppOperationTagEnum;
 use DR\Ipp\Enum\IppStatusCodeEnum;
 use DR\Ipp\Enum\IppTypeEnum;
-use RuntimeException;
 
 /**
  * @internal
  */
 class IppResponseParser implements IppResponseParserInterface
 {
+    private IppAttribute $lastAttribute;
+
+    /**
+     * @see https://datatracker.ietf.org/doc/html/rfc8010/#section-3.1
+     */
     public function getResponse(string $response): IppResponseInterface
     {
-        [, $response] = $this->consume($response, 2, IppTypeEnum::Int);            // version   0x0101
+        $state = new IppResponseState($response);
+
+        $state->consume(2, IppTypeEnum::Int);            // version   0x0101
         /** @var int $status */
-        [$status, $response] = $this->consume($response, 2, IppTypeEnum::Int);     // status    0x0502
-        [, $response] = $this->consume($response, 4, IppTypeEnum::Int);            // requestId 0x00000001
-        [, $response] = $this->consume($response, 1, IppTypeEnum::Int);            // IPPOperationTag::OPERATION_ATTRIBUTE_START
+        $status = $state->consume(2, IppTypeEnum::Int);  // status    0x0502
+        $state->consume(4, IppTypeEnum::Int);            // requestId 0x00000001
+        $state->consume(1, IppTypeEnum::Int);            // IPPOperationTag::OPERATION_ATTRIBUTE_START
 
         $attributesTags = [
             IppOperationTagEnum::JobAttributeStart->value,
             IppOperationTagEnum::PrinterAttributeStart->value,
             IppOperationTagEnum::UnsupportedAttributes->value,
         ];
         $attributes     = [];
-        while ($this->unpack('c', $response) !== IppOperationTagEnum::AttributeEnd->value) {
-            // look for attribute tag and remove it before parsing further attributes
-            if (in_array($this->unpack('c', $response), $attributesTags, true)) {
-                [, $response] = $this->consume($response, 1, null);
+        while ($state->getNextByte() !== IppOperationTagEnum::AttributeEnd->value) {
+            // look for an attribute tag and remove it before parsing further attributes
+            if (in_array($state->getNextByte(), $attributesTags, true)) {
+                $state->consume(1, null);
             }
 
-            [$attribute, $response] = $this->consumeAttribute($response);
+            $attribute = $this->getAttribute($state);
             $attributes[$attribute->getName()] = $attribute;
         }
         $statusCode = IppStatusCodeEnum::tryFrom($status) ?? IppStatusCodeEnum::Unknown;
@@ -46,78 +51,66 @@ public function getResponse(string $response): IppResponseInterface
     }
 
     /**
-     * Decodes an attribute from the response, and returns the decoded values and the rest of the response
-     * @return array{IppAttribute, string}
+     * @see https://datatracker.ietf.org/doc/html/rfc8010/#section-3.1.6
      */
-    private function consumeAttribute(string $response): array
+    private function getCollection(IppResponseState $state): IppCollection
     {
-        /** @var int $type */
-        [$type, $response] = $this->consume($response, 1, null);
-        [$nameLength, $response] = $this->consume($response, 2, IppTypeEnum::Int);
-        /** @var int $nameLength */
-        [$attrName, $response] = $this->consume($response, $nameLength, IppTypeEnum::NameWithoutLang);
-        /** @var string $attrName */
-        [$valueLength, $response] = $this->consume($response, 2, IppTypeEnum::Int);
-        /** @var int $valueLength */
-        [$attrValue, $response] = $this->consume(
-            $response,
-            $valueLength,
-            IppTypeEnum::tryFrom($type),
-        );
+        $collection = new IppCollection();
+
+        $state->consume(2, null); // 0x0000
+        while ($state->getNextByte() !== IppTypeEnum::EndCollection->value) {
+            $state->consume(3, null); // 0x4a 0x00 0x00
+
+            /** @var string $name */
+            $name = $this->getAttributeValue(IppTypeEnum::MemberAttributeName, $state);
+            /** @var int $valueType */
+            $valueType = $state->consume(1, null);
+            $state->consume(2, null); // 0x00 0x00
+
+            /** @var int $valueLength */
+            $valueLength = $state->consume(2, IppTypeEnum::Int);
+            $value = $state->consume($valueLength, IppTypeEnum::tryFrom($valueType));
+            $collection->add($name, $value);
+        }
+        $state->consume(5, null); // 0x37 0x00 0x00 0x00 0x00
 
-        return [new IppAttribute(IppTypeEnum::tryFrom($type) ?? IppTypeEnum::Int, $attrName, $attrValue), $response];
+        return $collection;
     }
 
     /**
-     * Decodes part of a binary string, and returns the decoded value and the rest of the binary string
-     * @return array{int|string|DateTime, string}
+     * Decodes an attribute from the response, and returns the decoded value(s)
      */
-    private function consume(string $response, int $length, ?IppTypeEnum $type): array
+    private function getAttribute(IppResponseState $state): IppAttribute
     {
-        switch ($type) {
-            case IppTypeEnum::Int:
-            case IppTypeEnum::Enum:
-                $unpack = $length === 2 ? 'n' : 'N';
-                break;
-            case IppTypeEnum::DateTime:
-                return [$this->unpackDateTime($response), substr($response, $length)];
-            case null:
-                $unpack = 'c' . $length;
-                break;
-            default:
-                $unpack = 'a' . $length;
-        }
-
-        return [$this->unpack($unpack, $response), substr($response, $length)];
-    }
+        /** @var int $type */
+        $type = $state->consume(1, null);
+        $attrType = IppTypeEnum::tryFrom($type);
 
-    private function unpackDateTime(string $response): DateTime
-    {
-        // Datetime in rfc2579 format: https://datatracker.ietf.org/doc/html/rfc2579
-        /** @var array{year: int, month: int, day: int, hour: int, min: int, sec: int, int, tz: string, tzhour:int, tzmin: int}|false $dateTime */
-        $dateTime = @unpack('nyear/cmonth/cday/chour/cmin/csec/c/atz/ctzhour/ctzmin', $response);
-        if ($dateTime === false) {
-            throw new RuntimeException('Failed to unpack IPP datetime');
+        /** @var int $nameLength */
+        $nameLength = $state->consume(2, IppTypeEnum::Int);
+        // Additional value https://datatracker.ietf.org/doc/html/rfc8010/#section-3.1.5
+        if ($nameLength === 0x0000) {
+            return $this->lastAttribute->appendValue($this->getAttributeValue($attrType, $state));
         }
-        $date     = $dateTime['year'] . '-' . $dateTime['month'] . '-' . $dateTime['day'];
-        $time     = $dateTime['hour'] . ':' . sprintf('%02d', $dateTime['min']) . ':' . sprintf('%02d', $dateTime['sec']);
-        $timeZone = $dateTime['tz'] . sprintf('%02d', $dateTime['tzhour']) . sprintf('%02d', $dateTime['tzmin']);
 
-        $converted = DateTime::createFromFormat('Y-n-j G:i:sO', $date . ' ' . $time . $timeZone);
-        if ($converted === false) {
-            throw new RuntimeException('Invalid DateTime in IPP attribute');
-        }
+        /** @var string $attrName */
+        $attrName = $state->consume($nameLength, IppTypeEnum::NameWithoutLang);
+        $attrValue = $this->getAttributeValue($attrType, $state);
+
+        $this->lastAttribute = new IppAttribute($attrType ?? IppTypeEnum::Int, $attrName, $attrValue);
 
-        return $converted;
+        return $this->lastAttribute;
     }
 
-    private function unpack(string $unpack, string $string): string|int
+    private function getAttributeValue(?IppTypeEnum $type, IppResponseState $state): mixed
     {
-        $data = @unpack($unpack, $string);
-        if ($data === false || isset($data[1]) === false || (is_string($data[1]) === false && is_int($data[1]) === false)) {
-            throw new RuntimeException();
+        if ($type === IppTypeEnum::Collection) {
+            return $this->getCollection($state);
         }
 
-        return $data[1];
+        /** @var int $valueLength */
+        $valueLength = $state->consume(2, IppTypeEnum::Int);
+
+        return $state->consume($valueLength, $type);
     }
 }