socket_wsaprotocol_info_export — Funktion · PHP-Referenz

Signatur

socket_wsaprotocol_info_export(Socket $socket, int $target_pid): string|false

Beschreibung

socket_wsaprotocol_info_export() ist eine Windows-spezifische Funktion, die die interne WSAPROTOCOL_INFO-Struktur eines Sockets serialisiert und für einen Zielprozess (angegeben durch seine Prozess-ID) exportiert. Der zurückgegebene String-Handle kann anschließend im Zielprozess mit socket_wsaprotocol_info_import() genutzt werden, um einen voll funktionsfähigen duplizierten Socket zu erzeugen.

Diese Funktion ist ausschließlich unter Windows verfügbar und verwendet intern die WinSock-2-API-Funktion WSADuplicateSocket(). Sie ermöglicht es, Sockets prozessübergreifend zu teilen – etwa wenn ein übergeordneter Prozess einen Socket erstellt und diesen an einen Child-Prozess (z. B. nach einem proc_open()-Aufruf) übergeben möchte.

Der typische Workflow besteht aus drei Schritten: (1) Export mit socket_wsaprotocol_info_export() im sendenden Prozess, (2) Übertragung des zurückgegebenen Handles an den Zielprozess (z. B. über eine Pipe oder gemeinsamen Speicher), (3) Import mit socket_wsaprotocol_info_import() im empfangenden Prozess. Nach erfolgreichem Import sollte das Handle mit socket_wsaprotocol_info_release() freigegeben werden.

Parameter

Name	Typ	Default	Beschreibung
$socket Pflicht	Socket		Das `Socket`-Objekt, dessen `WSAPROTOCOL_INFO`-Struktur exportiert werden soll. Muss ein gültiger, bereits erstellter Socket sein.
$target_pid Pflicht	int		Die Prozess-ID (PID) des Zielprozesses, der den Socket importieren soll. Die WinSock-API reserviert die Ressourcen für genau diesen Prozess.

Rückgabewert

Typ

string|false

Beschreibung

Gibt bei Erfolg einen String zurück, der das exportierte Handle repräsentiert und im Zielprozess an socket_wsaprotocol_info_import() übergeben werden kann. Bei einem Fehler wird false zurückgegeben; der Fehler kann mit socket_last_error() abgefragt werden.

Beispiele

Socket-Handle an einen Child-Prozess weitergeben

<?php
// Nur unter Windows verfügbar
if (PHP_OS_FAMILY !== 'Windows') {
    die('Diese Funktion ist nur unter Windows verfügbar.');
}

// Socket erstellen
$socket = socket_create(AF_INET, SOCK_STREAM, SOL_TCP);
if ($socket === false) {
    die('socket_create() fehlgeschlagen: ' . socket_strerror(socket_last_error()));
}

socket_bind($socket, '127.0.0.1', 0);
socket_listen($socket);

// Child-Prozess starten, der den Socket importieren soll
$descriptors = [
    0 => ['pipe', 'r'],
    1 => ['pipe', 'w'],
];
$child = proc_open('php child_process.php', $descriptors, $pipes);

if (is_resource($child)) {
    $status = proc_get_status($child);
    $childPid = $status['pid'];

    // WSAPROTOCOL_INFO für den Child-Prozess exportieren
    $handle = socket_wsaprotocol_info_export($socket, $childPid);
    if ($handle === false) {
        echo 'Export fehlgeschlagen: ' . socket_strerror(socket_last_error($socket)) . PHP_EOL;
    } else {
        // Handle an den Child-Prozess senden (z. B. über eine Pipe)
        fwrite($pipes[0], $handle . "\n");
        echo 'Handle erfolgreich exportiert: ' . $handle . PHP_EOL;
    }

    fclose($pipes[0]);
    fclose($pipes[1]);
    proc_close($child);
}

socket_close($socket);

Handle erfolgreich exportiert: <WSAPROTOCOL_INFO-Handle-String>

Fehlerbehandlung beim Export

<?php
if (PHP_OS_FAMILY !== 'Windows') {
    die('Nur unter Windows verfügbar.');
}

$socket = socket_create(AF_INET, SOCK_STREAM, SOL_TCP);

// Ungültige PID verwenden, um Fehlerverhalten zu demonstrieren
$handle = socket_wsaprotocol_info_export($socket, -1);

if ($handle === false) {
    $errCode = socket_last_error($socket);
    echo 'Fehler beim Exportieren: [' . $errCode . '] ' . socket_strerror($errCode) . PHP_EOL;
    socket_clear_error($socket);
} else {
    echo 'Handle: ' . $handle . PHP_EOL;
}

socket_close($socket);

Fehler beim Exportieren: [<Fehlercode>] <Fehlermeldung>

// Wichtig · Fallstricke

Nur Windows: Diese Funktion ist ausschließlich unter Windows verfügbar und existiert auf Linux/macOS nicht. PHP-Code, der diese Funktion verwendet, muss entsprechend abgesichert werden (z. B. mit PHP_OS_FAMILY === 'Windows').

Handle freigeben: Nach dem Import des Handles im Zielprozess sollte socket_wsaprotocol_info_release() aufgerufen werden, um die vom Betriebssystem reservierten Ressourcen wieder freizugeben und Speicherlecks zu vermeiden.

Sicherheit: Das exportierte Handle gewährt dem Zielprozess vollen Zugriff auf den Socket. Stellen Sie sicher, dass das Handle nur an vertrauenswürdige Prozesse weitergegeben wird und nicht über unsichere Kanäle übertragen wird.

Siehe auch

socket_wsaprotocol_info_import socket_wsaprotocol_info_release socket_create socket_last_error socket_strerror