<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.8 $ -->
<!-- splitted from ./en/functions/imap.xml, last change in rev 1.2 -->
  <refentry id="function.imap-open">
   <refnamediv>
    <refname>imap_open</refname>
    <refpurpose>Open an IMAP stream to a mailbox</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>resource</type><methodname>imap_open</methodname>
      <methodparam><type>string</type><parameter>mailbox</parameter></methodparam>
      <methodparam><type>string</type><parameter>username</parameter></methodparam>
      <methodparam><type>string</type><parameter>password</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>options</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns an IMAP stream on success and &false; on error.  This
     function can also be used to open streams to POP3 and NNTP
     servers, but some functions and features are only available
     on IMAP servers.  
    </para>
    <para>
     A mailbox name consists of a server part and a mailbox path on
     this server. The special name INBOX stands for the current users
     personal mailbox. The server part, which is enclosed in '{' and
     '}', consists of the servers name or ip address, an optional port
     (prefixed by ':'), and an optional protocol specification (prefixed
     by '/'). The server part is mandatory in all mailbox
     parameters. Mailbox names that contain international characters
     besides those in the printable ASCII space have to be encoded 
     with <function>imap_utf7_encode</function>.
    </para>
    <para>
     All names which start with <literal>{</literal> are remote names, and are
     in the form <literal>"{" remote_system_name [":" port] [flags] "}"
     [mailbox_name]</literal> where:
     <itemizedlist>
      <listitem>
       <simpara>
        <literal>remote_system_name</literal> - Internet domain name or
        bracketed IP address of server.
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <literal>port</literal> - optional TCP port number, default is the
        default port for that service          
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <literal>flags</literal> - optional flags, see following table.
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <literal>mailbox_name</literal> - remote mailbox name, default is INBOX
       </simpara>
      </listitem>
     </itemizedlist>
    </para>
    <para>
     <table>
      <title>Optional flags for names</title>
      <tgroup cols="2">
       <thead>
        <row>
         <entry>Flag</entry>
         <entry>Description</entry>
        </row>
       </thead>
       <tbody>
        <row>
         <entry><literal>/service=</literal><emphasis>service</emphasis></entry>
         <entry>mailbox access service, default is "imap"</entry>
        </row>
        <row>
         <entry><literal>/user=</literal><emphasis>user</emphasis></entry>
         <entry>remote user name for login on the server</entry>
        </row>
        <row>
         <entry><literal>/authuser=</literal><emphasis>user</emphasis></entry>
         <entry>remote authentication user; if specified this is the user name
          whose password is used (e.g. administrator)</entry>
        </row>
        <row>
         <entry><literal>/anonymous</literal></entry>
         <entry>remote access as anonymous user</entry>
        </row>
        <row>
         <entry><literal>/debug</literal></entry>
         <entry>record protocol telemetry in application's debug log</entry>
        </row>
        <row>
         <entry><literal>/secure</literal></entry>
         <entry>do not transmit a plaintext password over the network</entry>
        </row>
        <row>
         <entry><literal>/imap</literal>, <literal>/imap2</literal>,
          <literal>/imap2bis</literal>, <literal>/imap4</literal>,
          <literal>/imap4rev1</literal></entry>
         <entry>equivalent to /service=imap</entry>
        </row>
        <row>
         <entry><literal>/pop3</literal></entry>
         <entry>equivalent to /service=pop3</entry>
        </row>
        <row>
         <entry><literal>/nntp</literal></entry>
         <entry>equivalent to /service=nntp</entry>
        </row>
        <row>
         <entry><literal>/norsh</literal></entry>
         <entry>do not use rsh or ssh to establish a preauthenticated IMAP
          session</entry>
        </row>
        <row>
         <entry><literal>/ssl</literal></entry>
         <entry>use the Secure Socket Layer to encrypt the session</entry>
        </row>
        <row>
         <entry><literal>/validate-cert</literal></entry>
         <entry>validate certificates from TLS/SSL server (this is the default
          behavior)</entry>
        </row>
        <row>
         <entry><literal>/novalidate-cert</literal></entry>
         <entry>do not validate certificates from TLS/SSL server, needed if
          server uses self-signed certificates</entry>
        </row>
        <row>
         <entry><literal>/tls</literal></entry>
         <entry>force use of start-TLS to encrypt the session, and reject
          connection to servers that do not support it</entry>
        </row>
        <row>
         <entry><literal>/notls</literal></entry>
         <entry>do not do start-TLS to encrypt the session, even with servers
          that support it</entry>
        </row>
        <row>
         <entry><literal>/readonly</literal></entry>
         <entry>request read-only mailbox open (IMAP only; ignored on NNTP, and
          an error with SMTP and POP3)</entry>
        </row>
       </tbody>
      </tgroup>
     </table>
    </para>
    <para>
     The <parameter>options</parameter> are a bit mask with one or more of the following:
     <itemizedlist>
      <listitem>
       <simpara>
        <constant>OP_READONLY</constant> - Open mailbox read-only
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <constant>OP_ANONYMOUS</constant> - Don't use or update a
        <filename>.newsrc</filename> for news (NNTP only)
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <constant>OP_HALFOPEN</constant> - For IMAP and NNTP names, open a connection but
        don't open a mailbox.
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <constant>CL_EXPUNGE</constant> - Expunge mailbox automatically upon mailbox close
        (see also <function>imap_delete</function> and
        <function>imap_expunge</function>)
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <constant>OP_DEBUG</constant> - Debug protocol negotiations
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <constant>OP_SHORTCACHE</constant> - Short (elt-only) caching
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <constant>OP_SILENT</constant> - Don't pass up events (internal use)
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <constant>OP_PROTOTYPE</constant> - Return driver prototype
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <constant>OP_EXPUNGE</constant> - Silently expunge recycle stream
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <constant>OP_SECURE</constant> - Don't do non-secure authentication
       </simpara>
      </listitem>
     </itemizedlist>
    </para>
    <para>
     <example>
      <title>Different use of <function>imap_open</function></title>
      <programlisting role="php">
<![CDATA[
<?php
// To connect to an IMAP server running on port 143 on the local machine,
// do the following:
$mbox = imap_open("{localhost:143}INBOX", "user_id", "password");

// To connect to a POP3 server on port 110 on the local server, use:
$mbox = imap_open ("{localhost:110/pop3}INBOX", "user_id", "password");

// To connect to an SSL IMAP or POP3 server, add /ssl after the protocol
// specification:
$mbox = imap_open ("{localhost:993/imap/ssl}INBOX", "user_id", "password");

// To connect to an SSL IMAP or POP3 server with a self-signed certificate,
// add /ssl/novalidate-cert after the protocol specification:
$mbox = imap_open ("{localhost:995/pop3/ssl/novalidate-cert}", "user_id", "password");

// To connect to an NNTP server on port 119 on the local server, use:
$nntp = imap_open ("{localhost:119/nntp}comp.test", "", "");
// To connect to a remote server replace "localhost" with the name or the
// IP address of the server you want to connect to.
?>
]]>
      </programlisting>
     </example>
     </para>
    <para>
     <example>
      <title><function>imap_open</function> example</title>
      <programlisting role="php">
<![CDATA[
<?php
$mbox = imap_open("{your.imap.host:143}", "username", "password");

echo "<h1>Mailboxes</h1>\n";
$folders = imap_listmailbox($mbox, "{your.imap.host:143}", "*");

if ($folders == false) {
    echo "Call failed<br />\n";
} else {
    while (list ($key, $val) = each($folders)) {
        echo $val . "<br />\n";
    }
}

echo "<h1>Headers in INBOX</h1>\n";
$headers = imap_headers($mbox);

if ($headers == false) {
    echo "Call failed<br />\n";
} else {
    while (list ($key, $val) = each ($headers)) {
        echo $val . "<br />\n";
    }
}

imap_close($mbox);
?>
]]>
      </programlisting>
     </example>
    </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
-->