cvs: peardoc /en/core networking.xml

alexmerz Sun Jan 6 07:21:34 2002 EDT Added files: /peardoc/en/core networking.xml Log: add Net_Socket

Index: peardoc/en/core/networking.xml +++ peardoc/en/core/networking.xml <!-- $Id: networking.xml,v 1.1 2002/01/06 12:21:33 alexmerz Exp $ --> <reference id="core.networking"> <title>Networking functions</title> <titleabbrev>PEAR Log</titleabbrev> <partintro> <simpara> </simpara> </partintro> <refentry id="core.networking.Net_Socket"> <refnamediv> <refname><classname>Net_Socket</classname></refname> <refpurpose> Generalized Socket class </refpurpose> </refnamediv> <refsect1 id="core.networking.Net_Socket.desc"> <title>Description</title> <para> <classname>Socket</classname> enables comfortable handling Socket connections. </para> <example> <title>Using Socket</title> <programlisting role="php"> <![CDATA[ $socket = new Net_Socket() ; // open connection $socket -> connect( "http://www.example.com", 80, true, 30) ; // Send data including linebreak $socket -> writeLine( "String with data") ; // receive data until linebreak $empfang = $socket -> readLine() ; // receive a number of data $empfang = $socket -> read( 512) ; // close connection $empfang -> disconnect() ; ]]> </programlisting> </example> </refsect1> <refsect1 id="core.networking.Net_Socket.connect"> <title>Net_Socket::connect</title> <funcsynopsis> <funcprototype> <funcdef>mixed <function>Net_Socket::connect</function></funcdef> <paramdef>string <parameter>$addr</parameter></paramdef> <paramdef>integer <parameter>$port</parameter></paramdef> <paramdef>boolean <parameter> <optional>$persistent</optional></parameter></paramdef> <paramdef>integer <parameter> <optional>$timeout</optional></parameter></paramdef> </funcprototype> </funcsynopsis> <para> Connect to the specified port. If called when the socket is already connected, it disconnects and connects again. </para> <para> Parameter <itemizedlist> <listitem> <para> <parameter>$addr</parameter> - IP address or host name </para> </listitem> <listitem> <para> <parameter>$port</parameter> - TCP port number </para> </listitem> <listitem> <para> <parameter>$persistent</parameter> - whether the connection is persistent (kept open between requests by the web server). Default is <parameter>false</parameter>, no persistent connection </para> </listitem> <listitem> <para> <parameter>$timeout</parameter> - how long to wait for data </para> </listitem> </itemizedlist> </para> <para> Returns <itemizedlist> <listitem> <para> <parameter>mixed</parameter> - true on success or a PEAR_Error </para> </listitem> </itemizedlist> </para> </refsect1> <refsect1 id="core.networking.Net_Socket.disconnect"> <title>Net_Socket::disconnect</title> <funcsynopsis> <funcprototype> <funcdef>mixed <function>Net_Socket::disconnect</function></funcdef> <paramdef></paramdef> </funcprototype> </funcsynopsis> <para> Disconnects from the peer, closes the socket. </para> <para> Returns <itemizedlist> <listitem> <para> <parameter>mixed</parameter> - true on success or a PEAR_Error otherwise </para> </listitem> </itemizedlist> </para> </refsect1> <refsect1 id="core.networking.Net_Socket.isBlocking"> <title>Net_Socket::isBlocking</title> <funcsynopsis> <funcprototype> <funcdef>boolean <function>Net_Socket::isBlocking</function></funcdef> <paramdef></paramdef> </funcprototype> </funcsynopsis> <para> Find out if the socket is in <link linkend="core.networking.Net_Socket.setBlocking">blocking mode</link>. </para> <para> Returns <itemizedlist> <listitem> <para> <parameter>boolean</parameter> - the current blocking mode </para> </listitem> </itemizedlist> </para> </refsect1> <refsect1 id="core.networking.Net_Socket.setBlocking"> <title>Net_Socket::setBlocking</title> <funcsynopsis> <funcprototype> <funcdef>void <function>Net_Socket::setBlocking</function></funcdef> <paramdef>boolean <parameter>$mode</parameter></paramdef> </funcprototype> </funcsynopsis> <para> Sets whether the socket connection should be blocking or not. A read call to a non-blocking socket will return immediately if there is no data available, whereas it will block until there is data for blocking sockets. </para> <warning> <para> If you use <link linkend="core.networking.Net_Socket.readall"> <function>readAll</function></link> on a connection in blocking mode, the function will be not terminated until the socket connection will be closed. </para> </warning> <para> Parameter <itemizedlist> <listitem> <para> <parameter>$mode</parameter> - true for blocking sockets, false for nonblocking </para> </listitem> </itemizedlist> </para> </refsect1> <refsect1 id="core.networking.Net_Socket.gets"> <title>Net_Socket::gets</title> <funcsynopsis> <funcprototype> <funcdef>mixed <function>Net_Socket::gets</function></funcdef> <paramdef>integer <parameter>$size</parameter></paramdef> </funcprototype> </funcsynopsis> <para> Returns a string containing data from the socket connection </para> <para> Parameter <itemizedlist> <listitem> <para> <parameter>$size</parameter> - max number of chars to recieve </para> </listitem> </itemizedlist> </para> <para> Returns <itemizedlist> <listitem> <para> <parameter>mixed</parameter> - the data as string or a PEAR_Error on failure </para> </listitem> </itemizedlist> </para> </refsect1> <refsect1 id="core.networking.Net_Socket.read"> <title>Net_Socket::read</title> <funcsynopsis> <funcprototype> <funcdef>mixed <function>Net_Socket::read</function></funcdef> <paramdef>integer <parameter>$size</parameter></paramdef> </funcprototype> </funcsynopsis> <para> Read a specified amount of data. This is guaranteed to return, and has the added benefit of getting everything in one fread() chunk; if you know the size of the data you're getting beforehand, this is definitely the way to go. </para> <para> Parameter <itemizedlist> <listitem> <para> <parameter>$size</parameter> - max number of bytes to read from the socket </para> </listitem> </itemizedlist> </para> <para> Returns <itemizedlist> <listitem> <para> <parameter>mixed</parameter> - the data as string or a PEAR_Error if not connected </para> </listitem> </itemizedlist> </para> </refsect1> <refsect1 id="core.networking.Net_Socket.write"> <title>Net_Socket::write</title> <funcsynopsis> <funcprototype> <funcdef>mixed <function>Net_Socket::write</function></funcdef> <paramdef>string <parameter>$data</parameter></paramdef> </funcprototype> </funcsynopsis> <para> Write data to a socket connection </para> <para> Parameter <itemizedlist> <listitem> <para> <parameter>$data</parameter> - the data to write </para> </listitem> </itemizedlist> </para> <para> Returns <itemizedlist> <listitem> <para> <parameter>mixed</parameter> - PEAR_Error, if not connected or the message of the write function </para> </listitem> </itemizedlist> </para> </refsect1> <refsect1 id="core.networking.Net_Socket.writeLine"> <title>Net_Socket::writeLine</title> <funcsynopsis> <funcprototype> <funcdef>mixed <function>Net_Socket::writeLine</function></funcdef> <paramdef>string <parameter>$data</parameter></paramdef> </funcprototype> </funcsynopsis> <para> Write a line of data to a socket connection, followed by a trailing "\r\n". </para> <para> Parameter <itemizedlist> <listitem> <para> <parameter>$data</parameter> - the data to write </para> </listitem> </itemizedlist> </para> <para> Returns <itemizedlist> <listitem> <para> <parameter>mixed</parameter> - fputs result, or an PEAR_Error </para> </listitem> </itemizedlist> </para> </refsect1> <refsect1 id="core.networking.Net_Socket.eof"> <title>Net_Socket::eof</title> <funcsynopsis> <funcprototype> <funcdef>boolean <function>Net_Socket::eof</function></funcdef> <paramdef></paramdef> </funcprototype> </funcsynopsis> <para> fire true if the connection is closed or input stream finished </para> <para> Returns <itemizedlist> <listitem> <para> <parameter>boolean</parameter> - true, if no connection exists anymore </para> </listitem> </itemizedlist> </para> </refsect1> <refsect1 id="core.networking.Net_Socket.readByte"> <title>Net_Socket::readByte</title> <funcsynopsis> <funcprototype> <funcdef>mixed <function>Net_Socket::readByte</function></funcdef> <paramdef></paramdef> </funcprototype> </funcsynopsis> <para> Read a byte from the socket stream </para> <para> Returns <itemizedlist> <listitem> <para> <parameter>mixed</parameter> - data from the socket, or a PEAR_Error if not connected. </para> </listitem> </itemizedlist> </para> </refsect1> <refsect1 id="core.networking.Net_Socket.readWord"> <title>Net_Socket::readWord</title> <funcsynopsis> <funcprototype> <funcdef>mixed <function>Net_Socket::readWord</function></funcdef> <paramdef></paramdef> </funcprototype> </funcsynopsis> <para> Reads a word from the socket stream Word means a binary word, not a word in a language </para> <para> Returns <itemizedlist> <listitem> <para> <parameter>mixed</parameter> - data from the socket, or a PEAR_Error if not connected. </para> </listitem> </itemizedlist> </para> </refsect1> <refsect1 id="core.networking.Net_Socket.readInt"> <title>Net_Socket::readInt</title> <funcsynopsis> <funcprototype> <funcdef>mixed <function>Net_Socket::readInt</function></funcdef> <paramdef></paramdef> </funcprototype> </funcsynopsis> <para> Reads a integer number from the socket stream. The length of a integer is 4 bytes </para> <para> Returns <itemizedlist> <listitem> <para> <parameter>mixed</parameter> - data from the socket, or a PEAR_Error if not connected. </para> </listitem> </itemizedlist> </para> </refsect1> <refsect1 id="core.networking.Net_Socket.readIPAddress"> <title>Net_Socket::readIPAddress</title> <funcsynopsis> <funcprototype> <funcdef>mixed <function>Net_Socket::readIPAddress</function></funcdef> <paramdef></paramdef> </funcprototype> </funcsynopsis> <para> Reads a IP from the socket stream The function expect a integer which will converted to a IP address. This function only works with IPv4 addresses. </para> <para> Returns <itemizedlist> <listitem> <para> <parameter>mixed</parameter> - data from the socket, or a PEAR_Error if not connected. </para> </listitem> </itemizedlist> </para> </refsect1> <refsect1 id="core.networking.Net_Socket.readLine"> <title>Net_Socket::readLine</title> <funcsynopsis> <funcprototype> <funcdef>mixed <function>Net_Socket::readLine</function></funcdef> <paramdef></paramdef> </funcprototype> </funcsynopsis> <para> Read until either the end of the socket or a newline, whichever comes first. Strips the trailing newline from the returned data. </para> <para> Returns <itemizedlist> <listitem> <para> <parameter>mixed</parameter> - All available data up to a newline, without that newline, or until the end of the socket as string. else a PEAR_Error when not connected. </para> </listitem> </itemizedlist> </para> </refsect1> <refsect1 id="core.networking.Net_Socket.readall"> <title>Net_Socket::readAll</title> <funcsynopsis> <funcprototype> <funcdef>mixed <function>Net_Socket::readAll</function></funcdef> <paramdef></paramdef> </funcprototype> </funcsynopsis> <para> Read until the socket closes. THIS FUNCTION WILL NOT EXIT if the socket is in blocking mode until the socket closes. </para> <para> Returns <itemizedlist> <listitem> <para> <parameter>mixed</parameter> - All data until the socket closes as string, or PEAR_Error if not connected. </para> </listitem> </itemizedlist> </para> </refsect1> </refentry> </reference>