<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="eventbufferevent.connecthost" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>EventBufferEvent::connectHost</refname>
  <refpurpose>Connects to a hostname with optionally asyncronous DNS resolving</refpurpose>
 </refnamediv>
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <modifier>public</modifier>
   <type>bool</type>
   <methodname>EventBufferEvent::connectHost</methodname>
   <methodparam>
    <type>EventDnsBase</type>
    <parameter>dns_base</parameter>
   </methodparam>
   <methodparam>
    <type>string</type>
    <parameter>hostname</parameter>
   </methodparam>
   <methodparam>
    <type>int</type>
    <parameter>port</parameter>
   </methodparam>
   <methodparam
   choice="opt">
    <type>int</type>
    <parameter>family</parameter>
    <initializer>EventUtil::AF_UNSPEC</initializer>
   </methodparam>
  </methodsynopsis>
  <para>
   Resolves the DNS name hostname, looking for addresses of type
   <parameter>family</parameter>
   (
   <literal>EventUtil::AF_*</literal>
   constants). If the name resolution fails, it invokes the event callback
   with an error event. If it succeeds, it launches a connection attempt just
   as
   <methodname>EventBufferEvent::connect</methodname>
   would.
  </para>
  <para>
   <parameter>dns_base</parameter>
   is optional. May be &null;, or an object created with
   <methodname>EventDnsBase::__construct</methodname>
   . For asyncronous hostname resolving pass a valid event dns base resource.
   Otherwise the hostname resolving will block.
  </para>
  <note>
   <para>
    <classname>EventDnsBase</classname>
    is available only if
    <literal>Event</literal>
    configured
    <option role="configure">--with-event-extra</option>
    (
    <literal>event_extra</literal>
    library,
    <emphasis>libevent protocol-specific functionality support including HTTP, DNS, and RPC</emphasis>
    ).
   </para>
  </note>
  <note>
   <para>
    <methodname>EventBufferEvent::connectHost</methodname>
    requires
    <literal>libevent-2.0.3-alpha</literal>
    or greater.
   </para>
  </note>
 </refsect1>
 <refsect1 role="parameters">
  &reftitle.parameters;
  <variablelist>
   <varlistentry>
    <term>
     <parameter>dns_base</parameter>
    </term>
    <listitem>
     <para>
      Object of
      <classname>EventDnsBase</classname>
      in case if DNS is to be resolved asyncronously. Otherwise &null;.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <parameter>hostname</parameter>
    </term>
    <listitem>
     <para>
      Hostname to connect to. Recognized formats are:
<screen>
<![CDATA[
 www.example.com (hostname)
 1.2.3.4 (ipv4address)
 ::1 (ipv6address)
[::1] ([ipv6address])
]]>
      </screen>
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <parameter>port</parameter>
    </term>
    <listitem>
     <para>
      Port number
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <parameter>family</parameter>
    </term>
    <listitem>
     <para>
      Address family.
      <constant>EventUtil::AF_UNSPEC</constant>
      ,
      <constant>EventUtil::AF_INET</constant>
      , or
      <constant>EventUtil::AF_INET6</constant>
      . See
      <link linkend="eventutil.constants">EventUtil constants</link>
      .
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   &return.success;
  </para>
 </refsect1>
 <refsect1 role="examples">
  &reftitle.examples;
  <example>
   <title>
    <function>EventBufferEvent::connectHost</function> example</title>
   <programlisting role="php">
<![CDATA[
<?php
/* Read callback */
function readcb($bev, $base) {
    //$input = $bev->input; //$bev->getInput();

    //$pos = $input->search("TTP");
    $pos = $bev->input->search("TTP");

    while (($n = $bev->input->remove($buf, 1024)) > 0) {
        echo $buf;
    }
}

/* Event callback */
function eventcb($bev, $events, $base) {
    if ($events & EventBufferEvent::CONNECTED) {
        echo "Connected.\n";
    } elseif ($events & (EventBufferEvent::ERROR | EventBufferEvent::EOF)) {
        if ($events & EventBufferEvent::ERROR) {
            echo "DNS error: ", $bev->getDnsErrorString(), PHP_EOL;
        }

        echo "Closing\n";
        $base->exit();
        exit("Done\n");
    }
}

$base = new EventBase();

$dns_base = new EventDnsBase($base, TRUE); // We'll use async DNS resolving
if (!$dns_base) {
    exit("Failed to init DNS Base\n");
}

$bev = new EventBufferEvent($base, /* use internal socket */ NULL,
    EventBufferEvent::OPT_CLOSE_ON_FREE | EventBufferEvent::OPT_DEFER_CALLBACKS,
    "readcb", /* writecb */ NULL, "eventcb", $base
);
if (!$bev) {
    exit("Failed creating bufferevent socket\n");
}

//$bev->setCallbacks("readcb", /* writecb */ NULL, "eventcb", $base);
$bev->enable(Event::READ | Event::WRITE);

$output = $bev->output; //$bev->getOutput();
if (!$output->add(
    "GET {$argv[2]} HTTP/1.0\r\n".
    "Host: {$argv[1]}\r\n".
    "Connection: Close\r\n\r\n"
)) {
    exit("Failed adding request to output buffer\n");
}

if (!$bev->connectHost($dns_base, $argv[1], 80, EventUtil::AF_UNSPEC)) {
    exit("Can't connect to host {$argv[1]}\n");
}

$base->dispatch();
?>
]]>
   </programlisting>
   &example.outputs.similar;
   <screen>
<![CDATA[
Connected.
HTTP/1.0 301 Moved Permanently
Location: http://www.google.co.uk/
Content-Type: text/html; charset=UTF-8
Date: Sat, 09 Mar 2013 12:21:19 GMT
Expires: Mon, 08 Apr 2013 12:21:19 GMT
Cache-Control: public, max-age=2592000
Server: gws
Content-Length: 221
X-XSS-Protection: 1; mode=block
X-Frame-Options: SAMEORIGIN

<HTML><HEAD><meta http-equiv="content-type" content="text/html;charset=utf-8">
<TITLE>301 Moved</TITLE></HEAD><BODY>
<H1>301 Moved</H1>
The document has moved
<A HREF="http://www.google.co.uk/">here</A>.
</BODY></HTML>
Closing
Done
]]>
   </screen>
  </example>
 </refsect1>
 <refsect1 role="seealso">
  &reftitle.seealso;
  <simplelist>
   <member>
    <methodname>EventBufferEvent::connect</methodname>
   </member>
  </simplelist>
 </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:"~/.phpdoc/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
-->