mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-16 00:48:54 +00:00
New stream socket API (to ultimately replace fsockopen)
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@122553 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Sara Golemon
parent
df666096f2
commit
7f77b5fdec
3 changed files with 240 additions and 1 deletions
|
|
@ -1,5 +1,5 @@
|
|||
<?xml version="1.0" encoding="iso-8859-1"?>
|
||||
<!-- $Revision: 1.2 $ -->
|
||||
<!-- $Revision: 1.3 $ -->
|
||||
<section id="stream.constants">
|
||||
&reftitle.constants;
|
||||
&extension.constants;
|
||||
|
|
@ -73,6 +73,18 @@
|
|||
should not raise any errors.
|
||||
</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>STREAM_CLIENT_ASYNC_CONNECT</constant></entry>
|
||||
<entry>Open client socket asynchronously. Used with
|
||||
<function>stream_socket_client</function>.
|
||||
</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>STREAM_CLIENT_PERSISTENT</constant></entry>
|
||||
<entry>Client socket opened with <function>stream_socket_client</function>
|
||||
should remain persistent between page loads.
|
||||
</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</informaltable>
|
||||
|
|
|
|||
70
reference/stream/functions/stream-get-transports.xml
Normal file
70
reference/stream/functions/stream-get-transports.xml
Normal file
|
|
@ -0,0 +1,70 @@
|
|||
<?xml version="1.0" encoding="iso-8859-1"?>
|
||||
<!-- $Revision: 1.1 $ -->
|
||||
<refentry id="function.stream-get-transports">
|
||||
<refnamediv>
|
||||
<refname>stream_get_transports</refname>
|
||||
<refpurpose>Retrieve list of registered socket transports</refpurpose>
|
||||
</refnamediv>
|
||||
<refsect1>
|
||||
<title>Description</title>
|
||||
<methodsynopsis>
|
||||
<type>array</type><methodname>stream_get_transports</methodname>
|
||||
<void/>
|
||||
</methodsynopsis>
|
||||
<simpara>
|
||||
Returns an indexed array containing the name of all socket transports
|
||||
available on the running system.
|
||||
</simpara>
|
||||
<para>
|
||||
<example>
|
||||
<title>Using <function>stream_get_transports</function></title>
|
||||
<programlisting role="php">
|
||||
<![CDATA[
|
||||
<?php
|
||||
$xportlist = stream_get_transports();
|
||||
print_r($xportlist);
|
||||
|
||||
/* Output will be similar to the following
|
||||
Note: there may be more or fewer
|
||||
transports in your version of PHP
|
||||
---------------------------------------
|
||||
Array (
|
||||
[0] => tcp
|
||||
[1] => udp
|
||||
[2] => unix
|
||||
[3] => udg
|
||||
)
|
||||
*/
|
||||
?>
|
||||
]]>
|
||||
</programlisting>
|
||||
</example>
|
||||
</para>
|
||||
<para>
|
||||
See also
|
||||
<function>stream_get_filters</function>, and
|
||||
<function>stream_get_wrappers</function>
|
||||
</para>
|
||||
</refsect1>
|
||||
</refentry>
|
||||
|
||||
<!-- Keep this comment at the end of the file
|
||||
Local variables:
|
||||
mode: sgml
|
||||
sgml-omittag:t
|
||||
sgml-shorttag:t
|
||||
sgml-minimize-attributes:nil
|
||||
sgml-always-quote-attributes:t
|
||||
sgml-indent-step:1
|
||||
sgml-indent-data:t
|
||||
indent-tabs-mode:nil
|
||||
sgml-parent-document:nil
|
||||
sgml-default-dtd-file:"../../../../manual.ced"
|
||||
sgml-exposed-tags:nil
|
||||
sgml-local-catalogs:nil
|
||||
sgml-local-ecat-files:nil
|
||||
End:
|
||||
vim600: syn=xml fen fdm=syntax fdl=2 si
|
||||
vim: et tw=78 syn=sgml
|
||||
vi: ts=1 sw=1
|
||||
-->
|
||||
157
reference/stream/functions/stream-socket-client.xml
Normal file
157
reference/stream/functions/stream-socket-client.xml
Normal file
|
|
@ -0,0 +1,157 @@
|
|||
<?xml version="1.0" encoding="iso-8859-1"?>
|
||||
<!-- $Revision: 1.1 $ -->
|
||||
<refentry id="function.stream-socket-client">
|
||||
<refnamediv>
|
||||
<refname>stream_socket_client</refname>
|
||||
<refpurpose>
|
||||
Open Internet or Unix domain socket connection
|
||||
</refpurpose>
|
||||
</refnamediv>
|
||||
<refsect1>
|
||||
<title>Description</title>
|
||||
<methodsynopsis>
|
||||
<type>resource</type><methodname>stream_socket_client</methodname>
|
||||
<methodparam><type>string</type><parameter>remote_socket</parameter></methodparam>
|
||||
<methodparam choice="opt"><type>int</type><parameter>&errno</parameter></methodparam>
|
||||
<methodparam choice="opt"><type>string</type><parameter>&errstr</parameter></methodparam>
|
||||
<methodparam choice="opt"><type>float</type><parameter>timeout</parameter></methodparam>
|
||||
<methodparam choice="opt"><type>int</type><parameter>flags</parameter></methodparam>
|
||||
<methodparam choice="opt"><type>resource</type><parameter>context</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
<para>
|
||||
Initiates a stream or datagram connection to the destination specified
|
||||
by <parameter>remote_socket</parameter>. The type of socket created
|
||||
is determined by the transport specified using standard url formatting:
|
||||
<literal>transport://target</literal>. For Internet Domain sockets
|
||||
(AF_INET) such as TCP and UDP, the <literal>target</literal> portion
|
||||
of the <parameter>remote_socket</parameter> parameter should consist of
|
||||
a hostname or IP address followed by a colon and a port number. For Unix
|
||||
Domain sockets, the <parameter>target</parameter> portion should point
|
||||
to the socket file on the filesystem.
|
||||
|
||||
The optional <parameter>timeout</parameter> can be used to
|
||||
set a timeout in seconds for the connect system call.
|
||||
|
||||
<parameter>flags</parameter> is a bitmask field which may be set to any
|
||||
combination of connection flags. Currently the selection of connection
|
||||
flags is limited to <constant>STREAM_CLIENT_ASYNC_CONNECT</constant> and
|
||||
<constant>STREAM_CLIENT_PERSISTENT</constant>.
|
||||
</para>
|
||||
<note>
|
||||
<simpara>
|
||||
If you need to set a timeout for reading/writing data over the socket,
|
||||
use <function>stream_set_timeout</function>, as the <parameter>timeout</parameter>
|
||||
parameter to <function>stream_socket_client</function> only applies while
|
||||
connecting the socket.
|
||||
</simpara>
|
||||
</note>
|
||||
<para>
|
||||
<function>stream_socket_client</function> returns a
|
||||
stream resource which may
|
||||
be used together with the other file functions (such as
|
||||
<function>fgets</function>, <function>fgetss</function>,
|
||||
<function>fputs</function>, <function>fclose</function>, and
|
||||
<function>feof</function>).
|
||||
</para>
|
||||
<para>
|
||||
If the call fails, it will return &false; and if the optional
|
||||
<parameter>errno</parameter> and <parameter>errstr</parameter>
|
||||
arguments are present they will be set to indicate the actual
|
||||
system level error that occurred in the system-level
|
||||
<literal>connect()</literal> call. If the value returned in
|
||||
<parameter>errno</parameter> is <literal>0</literal> and the
|
||||
function returned &false;, it is an indication that the error
|
||||
occurred before the <literal>connect()</literal> call. This is
|
||||
most likely due to a problem initializing the socket. Note that
|
||||
the <parameter>errno</parameter> and
|
||||
<parameter>errstr</parameter> arguments will always be passed by
|
||||
reference.
|
||||
</para>
|
||||
<para>
|
||||
Depending on the environment, the Unix domain or the optional
|
||||
connect timeout may not be available. A list of available
|
||||
transports can be retrieved using <function>stream_get_transports</function>.
|
||||
</para>
|
||||
<para>
|
||||
The stream will by default be opened in blocking mode. You can
|
||||
switch it to non-blocking mode by using
|
||||
<function>stream_set_blocking</function>.
|
||||
<example>
|
||||
<title><function>stream_socket_client</function> Example</title>
|
||||
<programlisting role="php">
|
||||
<![CDATA[
|
||||
<?php
|
||||
$fp = stream_socket_client("tcp://www.example.com:80", $errno, $errstr, 30);
|
||||
if (!$fp) {
|
||||
echo "$errstr ($errno)<br>\n";
|
||||
} else {
|
||||
fputs ($fp, "GET / HTTP/1.0\r\nHost: www.example.com\r\nAccept: */*\r\n\r\n");
|
||||
while (!feof($fp)) {
|
||||
echo fgets ($fp,1024);
|
||||
}
|
||||
fclose ($fp);
|
||||
}
|
||||
?>
|
||||
]]>
|
||||
</programlisting>
|
||||
</example>
|
||||
The example below shows how to retrieve the day and time
|
||||
from the UDP service "daytime" (port 13) in your own machine.
|
||||
<example>
|
||||
<title>Using UDP connection</title>
|
||||
<programlisting role="php">
|
||||
<![CDATA[
|
||||
<?php
|
||||
$fp = stream_socket_client("udp://127.0.0.1:13", $errno, $errstr);
|
||||
if (!$fp) {
|
||||
echo "ERROR: $errno - $errstr<br>\n";
|
||||
} else {
|
||||
fwrite($fp,"\n");
|
||||
echo fread($fp, 26);
|
||||
fclose($fp);
|
||||
}
|
||||
?>
|
||||
]]>
|
||||
</programlisting>
|
||||
</example>
|
||||
<warning>
|
||||
<simpara>
|
||||
UDP sockets will sometimes appear to have opened without an error,
|
||||
even if the remote host is unreachable. The error will only
|
||||
become apparent when you read or write data to/from the socket.
|
||||
The reason for this is because UDP is a "connectionless" protocol,
|
||||
which means that the operating system does not try to establish
|
||||
a link for the socket until it actually needs to send or receive data.
|
||||
</simpara>
|
||||
</warning>
|
||||
See also <function>stream_socket_server</function>,
|
||||
<function>stream_set_blocking</function>,
|
||||
<function>stream_set_timeout</function>,
|
||||
<function>fgets</function>,
|
||||
<function>fgetss</function>, <function>fputs</function>,
|
||||
<function>fclose</function>, <function>feof</function>, and
|
||||
the <link linkend="ref.curl">Curl extension</link>.
|
||||
</para>
|
||||
</refsect1>
|
||||
</refentry>
|
||||
|
||||
<!-- Keep this comment at the end of the file
|
||||
Local variables:
|
||||
mode: sgml
|
||||
sgml-omittag:t
|
||||
sgml-shorttag:t
|
||||
sgml-minimize-attributes:nil
|
||||
sgml-always-quote-attributes:t
|
||||
sgml-indent-step:1
|
||||
sgml-indent-data:t
|
||||
indent-tabs-mode:nil
|
||||
sgml-parent-document:nil
|
||||
sgml-default-dtd-file:"../../../../manual.ced"
|
||||
sgml-exposed-tags:nil
|
||||
sgml-local-catalogs:nil
|
||||
sgml-local-ecat-files:nil
|
||||
End:
|
||||
vim600: syn=xml fen fdm=syntax fdl=2 si
|
||||
vim: et tw=78 syn=sgml
|
||||
vi: ts=1 sw=1
|
||||
-->
|
||||
Loading…
Reference in a new issue