/ 
Quiq-1.222
River stage zero No dependents
/ Quiq::Http::Message

NAME

Quiq::Http::Message - HTTP-Nachricht

BASE CLASS

Quiq::Hash

DESCRIPTION

Ein Objekt dieser Klasse repräsentiert eine HTTP-Nachricht. Eine HTTP-Nachricht besteht aus einer oder mehreren Kopfzeilen (Header) und einem optionalen Rumpf (Body). Kopfzeilen und Rumpf werden von der Klasse als Attribute implementiert, die durch Methoden der Klasse manipuliert werden können. Eine HTTP-Nachricht, die versendet werden kann, entsteht durch Erzeugen einer Stringrepräsentation des Objekts.

Die Klasse kann für HTTP-Requests als auch für HTTP-Responses verwendet werden. Ggf. müssen weitere Header eingeführt werden.

MEMO: Die Klasse ist nach dem Vorbild von R1::HttpResponse entstanden. Diese sollte so angepasst werden, dass sie Quiq::Http::Message als Basisklasse verwendet.

EXAMPLES

Einfache HTTP-Nachricht

my $msg = Quiq::Http::Message->new(
    contentType => 'text/plain',
    body => "Hello world\n"
);
print $msg->asString;

generiert auf STDOUT

Content-Type: text/plain
Content-Length: 12

Hello world

HTTP-Nachricht über Socket schicken (siehe auch Quiq::Http::Client)

my $sock = Quiq::Socket->new($host,$port);

my $msg = Quiq::Http::Message->new(
    contentType => 'text/plain',
    body => "Hello world\n"
);

print $sock $msg->asString;

HTTP-Nachricht vom Server empfangen

my $msg = Quiq::Http::Message->new(received=>1,$socket);
print $msg->asString;

Die Setzung received=>1 bewirkt, dass wir bei der Auswertung der Headerzeilen nicht strikt sind, d.h. bei unbekannten Headern wird keine Exception geworfen, und die Methode $msg->asString() liefert die Headerinformation exakt so wie sie empfangen wurde, d.h. sie wird nicht aus den Attributen gewonnen.

HTTP-Nachricht aus Datei

my $msg = Quiq::Http::Message->new('http/message01.txt');
print $msg->asString;

METHODS

Konstruktor

new() - Instantiiere ein HTTP Nachrichten-Objekt

Synopsis

$http = $class->new(@keyVal);
$http = $class->new(@keyVal,$fh);
$http = $class->new(@keyVal,$file);
$http = $class->new(@keyVal,\$str);

Returns

Referenz auf HTTP-Objekt.

Description

Instantiiere ein HTTP Nachrichten-Objekt mit den Eigenschaften @keyVal.

Folgende Eigenschaften können (u.a.) gesetzt werden:

  • contentType => $type

  • charset => $charset

  • contentLength => $n | -1

  • expires => $date | 'now' | 0

  • location => $url

  • setCookie => [$name=>$value,@keyVal]

  • refresh => [$n,$url]

  • body => $data

Zum Setzen von Eigenschaften siehe auch die Methoden $msg->set() und $msg->fromString().

Ist eine ungerade Anzahl an Parametern angegeben, wird zunächst die (ggf. leere) Liste von Attribut/Wert-Paaren @keyVal zugewiesen. Alle weiteren Eigenschaften werden via Handle $fh, Datei $file oder String $str gewonnen.

Attribute

set() - Setze Objekteigenschaften

Synopsis

$http->set(@keyVal);

Returns

Die Methode liefert keinen Wert zurück.

Description

Setze die Objekteigenschaften @keyVal. Für die Liste der Eigenschaften siehe new().

Examples

Ein HTTP-Request ohne Inhalt:

$http->set(
    host => $host,
    connection => 'close',
);

Eine HTTP-Response:

$http->set(
    contentType => 'text/html',
    charset => 'utf-8',
    setCookie => [id=>4711],
    setCookie => [user=>'seitzf'],
    body => "Test\n",
);

Kopfzeilen (Header)

Dieser Abschnitt beschreibt die Methoden zum Setzen und Abfragen von Kopfzeilen. Generell gilt: Ist ein Argument angegeben, wird die betreffende Kopfzeile gesetzt. Ist kein Argument angegeben, wird der Wert der Kopfzeile geliefert.

Der Name der Methode entspricht dem Namen der HTTP-Kopfzeile unter Anwendung folgender Transformationsregeln:

  • der erste Buchstabe ist klein geschrieben

  • Bindestriche sind entfernt

  • mehrere Worte sind in "camel case" zusammengesetzt

Beispiel: Die Kopfzeile "Content-Type" wird von der Methode contentType() verwaltet.

Der Wert einer Kopfzeilen-Methode ist nicht immer eine Zeichenkette. Er kann auch eine Datenstruktur sein. Dies hängt von der jeweiligen Kopfzeile ab. Im Skalarkontext wird eine Referenz auf die Datenstruktur geliefert, im Array-Kontext die Liste der Elemente (siehe contentType() oder setCookie()).

received() - Setze/Liefere received-Eigenschaft

Synopsis

$bool = $http->received($bool);
$bool = $http->received;

protocol() - Setze/Liefere Protokoll-Bezeichnung

Synopsis

$protocol = $http->protocol($protocol);
$protocol = $http->protocol;

Description

Die Protokoll-Bezeichnung steht in der ersten Zeile einer Server-Antwort und hat die Form "HTTP/X.Y".

status() - Setze/Liefere HTTP-Status

Synopsis

$status = $http->status($status);
$status = $http->status;

Description

Der Status steht in der ersten Zeile einer Server-Antwort und ist ein dreistelliger Code in der Form NNN.

statusText() - Setze/Liefere HTTP-StatusText

Synopsis

$statusText = $http->statusText($statusText);
$statusText = $http->statusText;

Description

Der StatusText steht in der ersten Zeile einer Server-Antwort und ist eine textuelle Beschreibung des Statuscode.

contentType() - Setze/Liefere Content-Type Header

Synopsis

$type = $http->contentType($type);
$type = $http->contentType;

charset() - Setze/Liefere Charset

Synopsis

$charset = $http->charset($charset);
$charset = $http->charset;

Description

Setze/Liefere den Zeichensatz, der ergänzend im Content-Type Header angegeben wird.

authorization() - Setze/Liefere Authorization-Information

Synopsis

$userPass = $http->authorization($userPass);
$userPass = $http->authorization;

transferEncoding() - Setze/Liefere Transfer-Encoding

Synopsis

$val = $http->transferEncoding($val);
$val = $http->transferEncoding;

contentLength() - Setze/Liefere Content-Length Header

Synopsis

$n = $http->contentLength($n);
$n = $http->contentLength;

expires() - Setze/Liefere Expires Header

Synopsis

$val = $http->expires($val);
$val = $http->expires;

host() - Setze/Liefere Header Host:

Synopsis

$host = $http->host($host);
$host = $http->host;

userAgent() - Setze/Liefere Wert von Header UserAgent:

Synopsis

$userAgent = $http->userAgent($userAgent);
$userAgent = $http->userAgent;

connection() - Setze/Liefere Header Connection:

Synopsis

$val = $http->connection($val);
$val = $http->connection;

location() - Setze/Liefere Location: Header

Synopsis

$url = $http->location($val);
$url = $http->location;

refresh() - Setze/Liefere Refresh-Header

Synopsis

$http->refresh($n);
$http->refresh($n,$url);
($n,$url) = $http->refresh;
$arr = $http->refresh;

Synopsis

$http->setCookie($name=>$value,@options);
@cookies = $http->setCookie;
$cookieA = $http->setCookie;

Description

Definiere Cookie $name mit Wert $value und Optionen @options. Existiert Cookie $name bereits, wird seine Definition überschrieben. Die Methode liefert beim Setzen keinen Wert zurück.

Ohne Parameter gerufen liefert die Methode die Liste der Cookie-Objekte zurück. Im Skalarkontext wird eine Referenz auf die Liste geliefert.

Example

Generiere Id und setze permanenten Cookie, der nach 5 Jahren abläuft:

$id = Quiq::Converter->intToWord(time);
$http->setCookie(
    id => $id,
    expires => '+5y',
);

Rumpf (Body)

Der Body der HTTP-Antwort ist per Default leer, d.h. sein Wert ist, sofern beim Konstruktoraufruf nichts anderes angegeben wird, ein Leerstring.

Der Body kann gesetzt werden:

$http->body($data);

Oder er kann per Referenz "in place" manipuliert werden:

$ref = $http->bodyRef;
$$ref =~ /__TIME__/strftime '%F %H:%M:%S %Z',localtime/eg;

Sein Wert wird geliefert durch:

$data = $http->body;

body() - Setze/Liefere Body

Synopsis

$body = $http->body($body);
$body = $http->body;

bodyRef() - Liefere Referenz auf Body

Synopsis

$ref = $http->bodyRef;

append() - Füge Daten zum Rumpf hinzu

Synopsis

$http->append($data);

Externe Repräsentation

fromString() - Setze Objektattribute aus Zeichenkette

Synopsis

$http->fromString($fh);
$http->fromString($file);
$http->fromString(\$str);

Description

Die Methode liest eine HTTP-Message als Zeichenkette ein, zerlegt sie in ihre Bestandteile und weist die enthaltene Information den Komponenten des Objektes zu.

Als Quelle kann eine Handle (Filehandle, Socket) eine Datei (Dateiname) oder eine Zeichenkette (Skalar-Referenz) angegeben werden.

asString() - Liefere HTTP-Nachricht als Zeichenkette

Synopsis

$str = $http->asString;

VERSION

1.222

AUTHOR

Frank Seitz, http://fseitz.de/

COPYRIGHT

Copyright (C) 2024 Frank Seitz

LICENSE

This code is free software; you can redistribute it and/or modify it under the same terms as Perl itself.