adu Tue Mar 5 11:37:53 2002 EDT
Added files:
/phpdoc/ro/functions imap.xml
Log:
IMAP functions
Index: phpdoc/ro/functions/imap.xml
+++ phpdoc/ro/functions/imap.xml
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<reference id='ref.imap'>
<title>IMAP, POP3 �i NNTP</title>
<titleabbrev>IMAP</titleabbrev>
<partintro>
<simpara>
Pentru ca aceste func�ii s� poat� fi folosite, trebuie s� compila�i
PHP cu directiva <option role="configure">--with-imap</option>.
Este nevoie s� fie instalat� biblioteca c-client. Desc�rca�i ultima
versiune de la <ulink url="&url.imap;">&url.imap;</ulink> �i compila�i-o.
Apoi copia�i fi�ierul <filename>c-client/c-client.a</filename> �n
<filename>/usr/local/lib/libc-client.a</filename>
�i copia�i <filename>c-client/rfc822.h</filename>,
<filename>mail.h</filename> �i <filename>linkage.h</filename> �n
<filename>/usr/local/include</filename> sau �n alt director din calea
c�tre fi�iere incluse.
</simpara>
<simpara>
De notat c� aceste func�ii, in ciuda numelor pe care le au, nu sunt
limitate doar la protocolul <acronym>IMAP</acronym>. Biblioteca c-client
folosit� de ele suport�, de asemenea, metode pentru acces
<acronym>NNTP</acronym>,
<acronym>POP3</acronym> �i la o c�su�� po�tal� local�.
</simpara>
<para>
Acest document nu �i propune s� intre �n detalii pentru toate subiectele
atinse de aceste func�ii. Mai multe informa�ii pute�i citi �n
documenta�ia surselor bibliotecii c-client
(<filename>docs/internal.txt</filename>) precum �i �n urm�toarele documente RFC:
<itemizedlist>
<listitem>
<simpara>
<ulink url="&url.rfc;rfc2821.html">RFC2821</ulink>: Simple Mail
Transfer Protocol (SMTP).
</simpara>
</listitem>
<listitem>
<simpara>
<ulink url="&url.rfc;rfc2822.html">RFC2822</ulink>: Standard for
ARPA internet text messages.
</simpara>
</listitem>
<listitem>
<simpara>
<ulink url="&url.rfc;rfc2060.html">RFC2060</ulink>: Internet
Message Access Protocol (IMAP) Version 4rev1.
</simpara>
</listitem>
<listitem>
<simpara>
<ulink url="&url.rfc;rfc1939.html">RFC1939</ulink>: Post
Office Protocol Version 3 (POP3).
</simpara>
</listitem>
<listitem>
<simpara>
<ulink url="&url.rfc;rfc977.html">RFC977</ulink>: Network News
Transfer Protocol (NNTP).
</simpara>
</listitem>
<listitem>
<simpara>
<ulink url="&url.rfc;rfc2076.html">RFC2076</ulink>: Common
Internet Message Headers.
</simpara>
</listitem>
<listitem>
<simpara>
<ulink url="&url.rfc;rfc2045.html">RFC2045</ulink>, <ulink
url="&url.rfc;rfc2046.html">RFC2046</ulink>, <ulink
url="&url.rfc;rfc2047.html">RFC2047</ulink>, <ulink
url="&url.rfc;rfc2048.html">RFC2048</ulink> �i <ulink
url="&url.rfc;rfc2049.html">RFC2049</ulink>: Multipurpose
Internet Mail Extensions (MIME).
</simpara>
</listitem>
</itemizedlist>
O viziune mai detaliat� pute�i g�si �i �n c�r�ile
<ulink url="&url.email.book;">Programming Internet Email</ulink>
de David Wood �i <ulink url="&url.imap.book;">Managing
IMAP</ulink> de Dianna Mullet & Kevin Mullet.
</para>
</partintro>
<refentry id="function.imap-8bit">
<refnamediv>
<refname>imap_8bit</refname>
<refpurpose>
Converte�te un �ir de caractere pe 8 bi�i �ntr-un �ir de caractere
tip�ribil
</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>string</type><methodname>imap_8bit</methodname>
<methodparam><type>string</type><parameter>string</parameter></methodparam>
</methodsynopsis>
<para>
Converte�te un �ir de caractere pe 8 bi�i �ntr-un �ir de caractere
tip�ribil (conform cu <ulink url="&url.rfc;rfc2045.html">RFC2045</ulink>,
sec�iunea 6.7).
</para>
<para>
Returneaz� un �ir de caractere tip�ribil.
</para>
<para>
Mai consulta�i <function>imap_qprint</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.imap-alerts">
<refnamediv>
<refname>imap_alerts</refname>
<refpurpose>
Aceast� func�ie returneaz� toate mesajele de avertizare (dac� exist�)
care au ap�rut pe parcursul cererii paginii curente, sau din momentul
�n care stiva de mesaje a fost resetat�
</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>array</type><methodname>imap_alerts</methodname>
<void/>
</methodsynopsis>
<para>
Aceast� func�ie returneaz� toate mesajele IMAP de avertizare
generate din momentul ultimului apel al func�iei
<function>imap_alerts</function> sau din momentul inceperii execu�iei
scriptului. Apelul func�iei <function>imap_alerts</function>
This function returns an array of all of the IMAP alert messages
generated since the last <function>imap_alerts</function> call,
or the beginning of the page. When
<function>imap_alerts</function> is called, the alert stack is
subsequently cleared. The IMAP specification requires that these
messages be passed to the user.
</para>
</refsect1>
</refentry>
<refentry id="function.imap-append">
<refnamediv>
<refname>imap_append</refname>
<refpurpose>
Append a string message to a specified mailbox
</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>int</type><methodname>imap_append</methodname>
<methodparam><type>int</type><parameter>imap_stream</parameter></methodparam>
<methodparam><type>string</type><parameter>mbox</parameter></methodparam>
<methodparam><type>string</type><parameter>message</parameter></methodparam>
<methodparam
choice="opt"><type>string</type><parameter>flags</parameter></methodparam>
</methodsynopsis>
<para>
Returneaz� &true; on sucess, &false; on error.
</para>
<para>
<function>imap_append</function> appends a string message to the
specified mailbox <parameter>mbox</parameter>. If the optional
<parameter>flags</parameter> is specified, writes the
<parameter>flags</parameter> to that mailbox also.
</para>
<para>
When talking to the Cyrus IMAP server, you must use "\r\n" as
your end-of-line terminator instead of "\n" or the operation will
fail.
</para>
<para>
<example>
<title><function>imap_append</function> example</title>
<programlisting role="php">
<![CDATA[
$stream = imap_open("{your.imap.host}INBOX.Drafts","username", "password");
$check = imap_check($stream);
print "Msg Count before append: ". $check->Nmsgs."\n";
imap_append($stream,"{your.imap.host}INBOX.Drafts"
,"From: [EMAIL PROTECTED]\r\n"
."To: [EMAIL PROTECTED]\r\n"
."Subject: test\r\n"
."\r\n"
."this is a test message, please ignore\r\n"
);
$check = imap_check($stream);
print "Msg Count after append : ". $check->Nmsgs."\n";
imap_close($stream);
]]>
</programlisting>
</example>
</para>
</refsect1>
</refentry>
<refentry id="function.imap-base64">
<refnamediv>
<refname>imap_base64</refname>
<refpurpose>Decode BASE64 encoded text</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>string</type><methodname>imap_base64</methodname>
<methodparam><type>string</type><parameter>text</parameter></methodparam>
</methodsynopsis>
<para>
<function>imap_base64</function> function decodes BASE-64 encoded
text (see <ulink url="&url.rfc;rfc2045.html">RFC2045</ulink>,
Section 6.8). The decoded message is returned as a string.
</para>
<para>
See also <function>imap_binary</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.imap-binary">
<refnamediv>
<refname>imap_binary</refname>
<refpurpose>
Convert an 8bit string to a base64 string
</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>string</type><methodname>imap_binary</methodname>
<methodparam><type>string</type><parameter>string</parameter></methodparam>
</methodsynopsis>
<para>
Convert an 8bit string to a base64 string (according to <ulink
url="&url.rfc;rfc2045.html">RFC2045</ulink>, Section 6.8).
</para>
<para>
Returneaz� a base64 string.
</para>
<para>
See also <function>imap_base64</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.imap-body">
<refnamediv>
<refname>imap_body</refname>
<refpurpose>Read the message body</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>string</type><methodname>imap_body</methodname>
<methodparam><type>int</type><parameter>imap_stream</parameter></methodparam>
<methodparam><type>int</type><parameter>msg_number</parameter></methodparam>
<methodparam
choice="opt"><type>int</type><parameter>flags</parameter></methodparam>
</methodsynopsis>
<para>
<function>imap_body</function> returns the body of the message,
numbered <parameter> msg_number</parameter> in the current
mailbox. The optional <parameter>flags</parameter> are a bit mask
with one or more of the following:
<itemizedlist>
<listitem>
<simpara>
FT_UID - The <parameter>msgno</parameter> is a UID
</simpara>
</listitem>
<listitem>
<simpara>
FT_PEEK - Do not set the \Seen flag if not already set
</simpara>
</listitem>
<listitem>
<simpara>
FT_INTERNAL - The return string is in internal format, will
not canonicalize to CRLF.
</simpara>
</listitem>
</itemizedlist>
</para>
<para>
<function>imap_body</function> will only return a verbatim copy of the
message body. To extract single parts of a multipart MIME-encoded
message you have to use <function>imap_fetchstructure</function> to
analyze its structure and <function>imap_fetchbody</function> to
extract a copy of a single body component.
</para>
</refsect1>
</refentry>
<refentry id='function.imap-bodystruct'>
<refnamediv>
<refname>imap_bodystruct</refname>
<refpurpose>
Read the structure of a specified body section of a specific message
</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>object</type><methodname>imap_bodystruct</methodname>
<methodparam><type>int</type><parameter>stream_id</parameter></methodparam>
<methodparam><type>int</type><parameter>msg_no</parameter></methodparam>
<methodparam><type>int</type><parameter>section</parameter></methodparam>
</methodsynopsis>
<para>
&warn.undocumented.func;
</para>
</refsect1>
</refentry>
<refentry id="function.imap-check">
<refnamediv>
<refname>imap_check</refname>
<refpurpose>Check current mailbox</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>object</type><methodname>imap_check</methodname>
<methodparam><type>int</type><parameter>imap_stream</parameter></methodparam>
</methodsynopsis>
<para>
Returneaz� information about the current mailbox. Returneaz� &false; on
failure.
</para>
<para>
The <function>imap_check</function> function checks the current
mailbox status on the server and returns the information in an
object with following properties:
</para>
<para>
<itemizedlist>
<listitem>
<simpara>
Date - last change of mailbox contents
</simpara>
</listitem>
<listitem>
<simpara>
Driver - protocol used to access this mailbox: POP3, IMAP, NNTP
</simpara>
</listitem>
<listitem>
<simpara>
Mailbox - the mailbox name
</simpara>
</listitem>
<listitem>
<simpara>
Nmsgs - number of messages in the mailbox
</simpara>
</listitem>
<listitem>
<simpara>
Recent - number of recent messages in the mailbox
</simpara>
</listitem>
</itemizedlist>
</para>
</refsect1>
</refentry>
<refentry id="function.imap-clearflag-full">
<refnamediv>
<refname>imap_clearflag_full</refname>
<refpurpose>Clears flags on messages</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>string</type><methodname>imap_clearflag_full</methodname>
<methodparam><type>int</type><parameter>stream</parameter></methodparam>
<methodparam><type>string</type><parameter>sequence</parameter></methodparam>
<methodparam><type>string</type><parameter>flag</parameter></methodparam>
<methodparam><type>string</type><parameter>options</parameter></methodparam>
</methodsynopsis>
<para>
This function causes a store to delete the specified flag to the
flags set for the messages in the specified sequence.
The flags which you can unset are "\\Seen", "\\Answered",
"\\Flagged", "\\Deleted", "\\Draft", and "\\Recent" (as defined
by RFC2060).
</para>
<para>
The options are a bit mask with one or more of the following:
<informalexample>
<literallayout>
ST_UID The sequence argument contains UIDs instead of
sequence numbers
</literallayout>
</informalexample>
</para>
</refsect1>
</refentry>
<refentry id="function.imap-close">
<refnamediv>
<refname>imap_close</refname>
<refpurpose>Close an IMAP stream</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>int</type><methodname>imap_close</methodname>
<methodparam><type>int</type><parameter>imap_stream</parameter></methodparam>
<methodparam
choice="opt"><type>int</type><parameter>flags</parameter></methodparam>
</methodsynopsis>
<para>
Close the imap stream. Takes an optional
<parameter>flag</parameter> CL_EXPUNGE, which will silently
expunge the mailbox before closing, removing all messages marked for
deletion.
</para>
</refsect1>
</refentry>
<refentry id="function.imap-createmailbox">
<refnamediv>
<refname>imap_createmailbox</refname>
<refpurpose>Create a new mailbox</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>int</type><methodname>imap_createmailbox</methodname>
<methodparam><type>int</type><parameter>imap_stream</parameter></methodparam>
<methodparam><type>string</type><parameter>mbox</parameter></methodparam>
</methodsynopsis>
<para>
<function>imap_createmailbox</function> creates a new mailbox
specified by <parameter>mbox</parameter>. Names containing
international characters should be encoded by
<function>imap_utf7_encode</function>
</para>
<para>
Returneaz� &true; on success and &false; on error.
</para>
<para>
See also <function>imap_renamemailbox</function>,
<function>imap_deletemailbox</function> and
<function>imap_open</function> for the format
of <parameter>mbox</parameter> names.
</para>
<para>
<example>
<title><function>imap_createmailbox</function> example</title>
<programlisting>
<![CDATA[
$mbox = imap_open("{your.imap.host}","username","password",OP_HALFOPEN)
or die("can't connect: ".imap_last_error());
$name1 = "phpnewbox";
$name2 = imap_utf7_encode("phpnewböx");
$newname = $name1;
echo "Newname will be '$name1'<br>\n";
# we will now create a new mailbox "phptestbox" in your inbox folder,
# check its status after creation and finaly remove it to restore
# your inbox to its initial state
if(@imap_createmailbox($mbox,imap_utf7_encode("{your.imap.host}INBOX.$newname"))) {
$status = @imap_status($mbox,"{your.imap.host}INBOX.$newname",SA_ALL);
if($status) {
print("your new mailbox '$name1' has the following status:<br>\n");
print("Messages: ". $status->messages )."<br>\n";
print("Recent: ". $status->recent )."<br>\n";
print("Unseen: ". $status->unseen )."<br>\n";
print("UIDnext: ". $status->uidnext )."<br>\n";
print("UIDvalidity:". $status->uidvalidity)."<br>\n";
if(imap_renamemailbox($mbox,"{your.imap.host}INBOX.$newname","{your.imap.host}INBOX.$name2"))
{
echo "renamed new mailbox from '$name1' to '$name2'<br>\n";
$newname=$name2;
} else {
print "imap_renamemailbox on new mailbox failed: ".imap_last_error()."<br>\n";
}
} else {
print "imap_status on new mailbox failed: ".imap_last_error()."<br>\n";
}
if(@imap_deletemailbox($mbox,"{your.imap.host}INBOX.$newname")) {
print "new mailbox removed to restore initial state<br>\n";
} else {
print "imap_deletemailbox on new mailbox failed:
".implode("<br>\n",imap_errors())."<br>\n";
}
} else {
print "could not create new mailbox: ".implode("<br>\n",imap_errors())."<br>\n";
}
imap_close($mbox);
]]>
</programlisting>
</example>
</para>
</refsect1>
</refentry>
<refentry id="function.imap-delete">
<refnamediv>
<refname>imap_delete</refname>
<refpurpose>
Mark a messge for deletion from current mailbox
</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>int</type><methodname>imap_delete</methodname>
<methodparam><type>int</type><parameter>imap_stream</parameter></methodparam>
<methodparam><type>int</type><parameter>msg_number</parameter></methodparam>
<methodparam
choice="opt"><type>int</type><parameter>flags</parameter></methodparam>
</methodsynopsis>
<para>
Returneaz� &true;.
</para>
<para>
<function>imap_delete</function> marks messages listed
in <parameter>msg_number</parameter> for deletion. The optional
<parameter>flags</parameter> parameter only has a single option,
<parameter>FT_UID</parameter>, which tells the function to treat
the <parameter>msg_number</parameter> argument as a
<parameter>UID</parameter>. Messages marked for deletion will
stay in the mailbox until either
<function>imap_expunge</function> is called or
<function>imap_close</function> is called with the optional
parameter CL_EXPUNGE.
</para>
<note>
<para>
POP3 mailboxes do not have their message flags saved between
connections, so <function>imap_expunge</function> must be called during
the same connection in order for messages marked for deletion to
actually be purged.
</para>
</note>
<para>
<example>
<title><function>imap_delete</function> Beispiel</title>
<programlisting role="php">
<![CDATA[
$mbox = imap_open ("{your.imap.host}INBOX", "username", "password")
or die ("can't connect: " . imap_last_error());
$check = imap_mailboxmsginfo ($mbox);
print "Messages before delete: " . $check->Nmsgs . "<br>\n" ;
imap_delete ($mbox, 1);
$check = imap_mailboxmsginfo ($mbox);
print "Messages after delete: " . $check->Nmsgs . "<br>\n" ;
imap_expunge ($mbox);
$check = imap_mailboxmsginfo ($mbox);
print "Messages after expunge: " . $check->Nmsgs . "<br>\n" ;
imap_close ($mbox);
]]>
</programlisting>
</example>
</para>
</refsect1>
</refentry>
<refentry id="function.imap-deletemailbox">
<refnamediv>
<refname>imap_deletemailbox</refname>
<refpurpose>Delete a mailbox</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>int</type><methodname>imap_deletemailbox</methodname>
<methodparam><type>int</type><parameter>imap_stream</parameter></methodparam>
<methodparam><type>string</type><parameter>mbox</parameter></methodparam>
</methodsynopsis>
<para>
<function>imap_deletemailbox</function> deletes the specified
mailbox (see <function>imap_open</function> for the format
of <parameter>mbox</parameter> names).
</para>
<para>
Returneaz� &true; on success and &false; on error.
</para>
<para>
See also <function>imap_createmailbox</function>,
<function>imap_renamemailbox</function>, and
<function>imap_open</function> for the format of
<parameter>mbox</parameter>.
</para>
</refsect1>
</refentry>
<refentry id="function.imap-errors">
<refnamediv>
<refname>imap_errors</refname>
<refpurpose>
This function returns all of the IMAP errors (if any) that have
occurred during this page request or since the error stack was
reset.
</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>array</type><methodname>imap_errors</methodname>
<void/>
</methodsynopsis>
<para>
This function returns an array of all of the IMAP error messages
generated since the last <function>imap_errors</function> call,
or the beginning of the page. When
<function>imap_errors</function> is called, the error stack is
subsequently cleared.
</para>
</refsect1>
</refentry>
<refentry id="function.imap-expunge">
<refnamediv>
<refname>imap_expunge</refname>
<refpurpose>Delete all messages marked for deletion</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>int</type><methodname>imap_expunge</methodname>
<methodparam><type>int</type><parameter>imap_stream</parameter></methodparam>
</methodsynopsis>
<para>
<function>imap_expunge</function> deletes all the messages marked
for deletion by <function>imap_delete</function>,
<function>imap_mail_move</function>, or
<function>imap_setflag_full</function>.
</para>
<para>
Returneaz� &true;.
</para>
</refsect1>
</refentry>
<refentry id="function.imap-fetch-overview">
<refnamediv>
<refname>imap_fetch_overview</refname>
<refpurpose>
Read an overview of the information in the headers of the given message
</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>array</type><methodname>imap_fetch_overview</methodname>
<methodparam><type>int</type><parameter>imap_stream</parameter></methodparam>
<methodparam><type>string</type><parameter>sequence</parameter></methodparam>
<methodparam
choice="opt"><type>int</type><parameter>flags</parameter></methodparam>
</methodsynopsis>
<para>
This function fetches mail headers for the given
<parameter>sequence</parameter> and returns an overview of their
contents. <parameter>sequence</parameter> will contain a sequence
of message indices or UIDs, if <parameter>flags</parameter>
contains FT_UID. The returned value is an array of objects
describing one message header each:
<itemizedlist>
<listitem>
<simpara>
subject - the messages subject
</simpara>
</listitem>
<listitem>
<simpara>
from - who sent it
</simpara>
</listitem>
<listitem>
<simpara>
date - when was it sent
</simpara>
</listitem>
<listitem>
<simpara>
message_id - Message-ID
</simpara>
</listitem>
<listitem>
<simpara>
references - is a reference to this message id
</simpara>
</listitem>
<listitem>
<simpara>
size - size in bytes
</simpara>
</listitem>
<listitem>
<simpara>
uid - UID the message has in the mailbox
</simpara>
</listitem>
<listitem>
<simpara>
msgno - message sequence number in the maibox
</simpara>
</listitem>
<listitem>
<simpara>
recent - this message is flagged as recent
</simpara>
</listitem>
<listitem>
<simpara>
flagged - this message is flagged
</simpara>
</listitem>
<listitem>
<simpara>
answered - this message is flagged as answered
</simpara>
</listitem>
<listitem>
<simpara>
deleted - this message is flagged for deletion
</simpara>
</listitem>
<listitem>
<simpara>
seen - this message is flagged as already read
</simpara>
</listitem>
<listitem>
<simpara>
draft - this message is flagged as being a draft
</simpara>
</listitem>
</itemizedlist>
</para>
<para>
<example>
<title><function>imap_fetch_overview</function> example</title>
<programlisting role="php">
<![CDATA[
$mbox = imap_open("{your.imap.host:143}","username","password")
or die("can't connect: ".imap_last_error());
$overview = imap_fetch_overview($mbox,"2,4:6",0);
if(is_array($overview)) {
reset($overview);
while( list($key,$val) = each($overview)) {
print $val->msgno
. " - " . $val->date
. " - " . $val->subject
. "\n";
}
}
imap_close($mbox);
]]>
</programlisting>
</example>
</para>
</refsect1>
</refentry>
<refentry id="function.imap-fetchbody">
<refnamediv>
<refname>imap_fetchbody</refname>
<refpurpose>
Fetch a particular section of the body of the message
</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>string</type><methodname>imap_fetchbody</methodname>
<methodparam><type>int</type><parameter>imap_stream</parameter></methodparam>
<methodparam><type>int</type><parameter>msg_number</parameter></methodparam>
<methodparam><type>string</type><parameter>part_number</parameter></methodparam>
<methodparam
choice="opt"><type>flags</type><parameter>flags</parameter></methodparam>
</methodsynopsis>
<para>
This function causes a fetch of a particular section of the body
of the specified messages as a text string and returns that text
string. The section specification is a string of integers
delimited by period which index into a body part list as per the
IMAP4 specification. Body parts are not decoded by this function.
</para>
<para>
The options for <function>imap_fetchbody</function> is a bitmask
with one or more of the following:
<itemizedlist>
<listitem>
<simpara>
FT_UID - The <parameter>msg_number</parameter> is a UID
</simpara>
</listitem>
<listitem>
<simpara>
FT_PEEK - Do not set the \Seen flag if not already set
</simpara>
</listitem>
<listitem>
<simpara>
FT_INTERNAL - The return string is in "internal" format,
without any attempt to canonicalize CRLF.
</simpara>
</listitem>
</itemizedlist>
</para>
<para>
See also: <function>imap_fetchstructure</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.imap-fetchheader">
<refnamediv>
<refname>imap_fetchheader</refname>
<refpurpose>Returneaz� header for a message</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>string</type><methodname>imap_fetchheader</methodname>
<methodparam><type>int</type><parameter>imap_stream</parameter></methodparam>
<methodparam><type>int</type><parameter>msgno</parameter></methodparam>
<methodparam><type>int</type><parameter>flags</parameter></methodparam>
</methodsynopsis>
<para>
This function causes a fetch of the complete, unfiltered
<ulink url="&url.rfc;rfc2822.html">RFC2822</ulink>
format header of the specified message as a text string and
returns that text string.
</para>
<para>
The options are:
<informalexample>
<literallayout>
FT_UID The msgno argument is a UID
FT_INTERNAL The return string is in "internal" format,
without any attempt to canonicalize to CRLF
newlines
FT_PREFETCHTEXT The RFC822.TEXT should be pre-fetched at the
same time. This avoids an extra RTT on an
IMAP connection if a full message text is
desired (e.g. in a "save to local file"
operation)
</literallayout>
</informalexample>
</para>
</refsect1>
</refentry>
<refentry id="function.imap-fetchstructure">
<refnamediv>
<refname>imap_fetchstructure</refname>
<refpurpose>
Read the structure of a particular message
</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>object</type><methodname>imap_fetchstructure</methodname>
<methodparam><type>int</type><parameter>imap_stream</parameter></methodparam>
<methodparam><type>int</type><parameter>msg_number</parameter></methodparam>
<methodparam
choice="opt"><type>int</type><parameter>flags</parameter></methodparam>
</methodsynopsis>
<para>
This function fetches all the structured information for a given
message. The optional <parameter>flags</parameter> parameter only
has a single option, <parameter>FT_UID</parameter>, which tells
the function to treat the <parameter>msg_number</parameter>
argument as a <parameter>UID</parameter>. The returned object
includes the envelope, internal date, size, flags and body
structure along with a similar object for each mime
attachement. The structure of the returned objects is as follows:
</para>
<para>
<table>
<title>
Returned Objects for <function>imap_fetchstructure</function>
</title>
<tgroup cols="2">
<tbody>
<row>
<entry>type</entry>
<entry>Primary body type</entry>
</row>
<row>
<entry>encoding</entry>
<entry>Body transfer encoding</entry>
</row>
<row>
<entry>ifsubtype</entry>
<entry>&true; if there is a subtype string</entry>
</row>
<row>
<entry>subtype</entry>
<entry><acronym>MIME</acronym> subtype</entry>
</row>
<row>
<entry>ifdescription</entry>
<entry>&true; if there is a description string</entry>
</row>
<row>
<entry>description</entry>
<entry>Content description string</entry>
</row>
<row>
<entry>ifid</entry>
<entry>&true; if there is an identification string</entry>
</row>
<row>
<entry>id</entry>
<entry>Identification string</entry>
</row>
<row>
<entry>lines</entry>
<entry>Number of lines</entry>
</row>
<row>
<entry>bytes</entry>
<entry>Number of bytes</entry>
</row>
<row>
<entry>ifdisposition</entry>
<entry>&true; if there is a disposition string</entry>
</row>
<row>
<entry>disposition</entry>
<entry>Disposition string</entry>
</row>
<row>
<entry>ifdparameters</entry>
<entry>&true; if the dparameters array exists</entry>
</row>
<row>
<entry>dparameters</entry>
<entry>An array of objects where each object has an "attribute" and a
"value" property corresponding to the parameters on the
Content-disposition <acronym>MIME</acronym>header.</entry>
</row>
<row>
<entry>ifparameters</entry>
<entry>&true; if the parameters array exists</entry>
</row>
<row>
<entry>parameters</entry>
<entry>An array of objects where each object has an "attribute" and
a "value" property.</entry>
</row>
<row>
<entry>parts</entry>
<entry>An array of objects identical in structure to the top-level
object, each of which corresponds to a <acronym>MIME</acronym> body
part.</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<para>
<table>
<title>Primary body type</title>
<tgroup cols="2">
<tbody>
<row><entry>0</entry><entry>text</entry></row>
<row><entry>1</entry><entry>multipart</entry></row>
<row><entry>2</entry><entry>message</entry></row>
<row><entry>3</entry><entry>application</entry></row>
<row><entry>4</entry><entry>audio</entry></row>
<row><entry>5</entry><entry>image</entry></row>
<row><entry>6</entry><entry>video</entry></row>
<row><entry>7</entry><entry>other</entry></row>
</tbody>
</tgroup>
</table>
</para>
<para>
<table>
<title>Transfer encodings</title>
<tgroup cols="2">
<tbody>
<row><entry>0</entry><entry>7BIT</entry></row>
<row><entry>1</entry><entry>8BIT</entry></row>
<row><entry>2</entry><entry>BINARY</entry></row>
<row><entry>3</entry><entry>BASE64</entry></row>
<row><entry>4</entry><entry>QUOTED-PRINTABLE</entry></row>
<row><entry>5</entry><entry>OTHER</entry></row>
</tbody>
</tgroup>
</table>
</para>
<para>
See also: <function>imap_fetchbody</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.imap-get-quota">
<refnamediv>
<refname>imap_get_quota</refname>
<refpurpose>
Retrieve the quota level settings, and usage statics per mailbox
</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>array</type><methodname>imap_get_quota</methodname>
<methodparam><type>int</type><parameter>imap_stream</parameter></methodparam>
<methodparam><type>string</type><parameter>quota_root</parameter></methodparam>
</methodsynopsis>
<para>
Returneaz� an array with integer values limit and usage for the given
mailbox. The value of limit represents the total amount of space
allowed for this mailbox. The usage value represents the mailboxes
current level of capacity. Will return &false; in the case of failure.
</para>
<para>
This function is currently only available to users of the c-client2000
library.
</para>
<para>
<parameter>imap_stream</parameter> should be the value returned from
an <function>imap_status</function> call. This stream is required to
be opened as the mail admin user for the quota function to work.
<parameter>quota_root</parameter> should normally be in the form of
user.name where name is the mailbox you wish to retrieve information
about.
</para>
<para>
<example>
<title><function>imap_get_quota</function> example</title>
<programlisting role="php">
<![CDATA[
$mbox = imap_open("{your.imap.host}","mailadmin","password",OP_HALFOPEN)
or die("can't connect: ".imap_last_error());
$quota_value = imap_get_quota($mbox, "user.kalowsky");
if(is_array($quota_value)) {
print "Usage level is: " . $quota_value['usage'];
print "Limit level is: " . $quota_value['limit'];
}
imap_close($mbox);
]]>
</programlisting>
</example>
</para>
<para>
See also <function>imap_open</function>, <function>imap_set_quota</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.imap-getmailboxes">
<refnamediv>
<refname>imap_getmailboxes</refname>
<refpurpose>
Read the list of mailboxes, returning detailed information on
each one
</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>array</type><methodname>imap_getmailboxes</methodname>
<methodparam><type>int</type><parameter>imap_stream</parameter></methodparam>
<methodparam><type>string</type><parameter>ref</parameter></methodparam>
<methodparam><type>string</type><parameter>pattern</parameter></methodparam>
</methodsynopsis>
<para>
Returneaz� an array of objects containing mailbox information. Each
object has the attributes <parameter>name</parameter>, specifying
the full name of the mailbox; <parameter>delimiter</parameter>,
which is the hierarchy delimiter for the part of the hierarchy
this mailbox is in; and
<parameter>attributes</parameter>. <parameter>Attributes</parameter>
is a bitmask that can be tested against:
<itemizedlist>
<listitem>
<simpara>
LATT_NOINFERIORS - This mailbox has no "children" (there are
no mailboxes below this one).
</simpara>
</listitem>
<listitem>
<simpara>
LATT_NOSELECT - This is only a container, not a mailbox - you
cannot open it.
</simpara>
</listitem>
<listitem>
<simpara>
LATT_MARKED - This mailbox is marked. Only used by UW-IMAPD.
</simpara>
</listitem>
<listitem>
<simpara>
LATT_UNMARKED - This mailbox is not marked. Only used by
UW-IMAPD.
</simpara>
</listitem>
</itemizedlist>
</para>
<para>
Mailbox names containing international Characters outside the
printable ASCII range will be encoded and may be decoded by
<function>imap_utf7_decode</function>.
</para>
<para>
<parameter>ref</parameter> should normally be just the server
specification as described in <function>imap_open</function>, and
<parameter>pattern</parameter> specifies where in the mailbox
hierarchy to start searching. If you want all mailboxes, pass
'*' for <parameter>pattern</parameter>.
</para>
<para>
There are two special characters you can pass as part of the
<parameter>pattern</parameter>: '*' and '%'. '*' means to return
all mailboxes. If you pass <parameter>pattern</parameter> as '*',
you will get a list of the entire mailbox hierarchy. '%' means to
return the current level only. '%' as the
<parameter>pattern</parameter> parameter will return only the top
level mailboxes; '~/mail/%' on UW_IMAPD will return every mailbox
in the ~/mail directory, but none in subfolders of that
directory.
</para>
<para>
<example>
<title><function>imap_getmailboxes</function> example</title>
<programlisting role="php">
<![CDATA[
$mbox = imap_open("{your.imap.host}","username","password",OP_HALFOPEN)
or die("can't connect: ".imap_last_error());
$list = imap_getmailboxes($mbox,"{your.imap.host}","*");
if(is_array($list)) {
reset($list);
while (list($key, $val) = each($list))
{
print "($key) ";
print imap_utf7_decode($val->name).",";
print "'".$val->delimiter."',";
print $val->attributes."<br>\n";
}
} else
print "imap_getmailboxes failed: ".imap_last_error()."\n";
imap_close($mbox);
]]>
</programlisting>
</example>
</para>
<para>
See also <function>imap_getsubscribed</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.imap-getsubscribed">
<refnamediv>
<refname>imap_getsubscribed</refname>
<refpurpose>List all the subscribed mailboxes</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>array</type><methodname>imap_getsubscribed</methodname>
<methodparam><type>int</type><parameter>imap_stream</parameter></methodparam>
<methodparam><type>string</type><parameter>ref</parameter></methodparam>
<methodparam><type>string</type><parameter>pattern</parameter></methodparam>
</methodsynopsis>
<para>
This function is identical to
<function>imap_getmailboxes</function>, except that it only
returns mailboxes that the user is subscribed to.
</para>
</refsect1>
</refentry>
<refentry id="function.imap-header">
<refnamediv>
<refname>imap_header</refname>
<refpurpose>Read the header of the message</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>object</type><methodname>imap_header</methodname>
<methodparam><type>int</type><parameter>imap_stream</parameter></methodparam>
<methodparam><type>int</type><parameter>msg_number</parameter></methodparam>
<methodparam
choice="opt"><type>int</type><parameter>fromlength</parameter></methodparam>
<methodparam
choice="opt"><type>int</type><parameter>subjectlength</parameter></methodparam>
<methodparam
choice="opt"><type>string</type><parameter>defaulthost</parameter></methodparam>
</methodsynopsis>
<para>
This is an alias to <function>imap_headerinfo</function>
and is identical to this in any way.
</para>
</refsect1>
</refentry>
<refentry id="function.imap-headerinfo">
<refnamediv>
<refname>imap_headerinfo</refname>
<refpurpose>Read the header of the message</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>object</type><methodname>imap_headerinfo</methodname>
<methodparam><type>int</type><parameter>imap_stream</parameter></methodparam>
<methodparam><type>int</type><parameter>msg_number</parameter></methodparam>
<methodparam
choice="opt"><type>int</type><parameter>fromlength</parameter></methodparam>
<methodparam
choice="opt"><type>int</type><parameter>subjectlength</parameter></methodparam>
<methodparam
choice="opt"><type>string</type><parameter>defaulthost</parameter></methodparam>
</methodsynopsis>
<para>
This function returns an object of various header elements.
</para>
<para>
<informalexample>
<literallayout>
remail, date, Date, subject, Subject, in_reply_to, message_id,
newsgroups, followup_to, references
message flags:
Recent - 'R' if recent and seen,
'N' if recent and not seen,
' ' if not recent
Unseen - 'U' if not seen AND not recent,
' ' if seen OR not seen and recent
Answered -'A' if answered,
' ' if unanswered
Deleted - 'D' if deleted,
' ' if not deleted
Draft - 'X' if draft,
' ' if not draft
Flagged - 'F' if flagged,
' ' if not flagged
NOTE that the Recent/Unseen behavior is a little odd. If you want to
know if a message is Unseen, you must check for
Unseen == 'U' || Recent == 'N'
toaddress (full to: line, up to 1024 characters)
to[] (returns an array of objects from the To line, containing):
personal
adl
mailbox
host
fromaddress (full from: line, up to 1024 characters)
from[] (returns an array of objects from the From line, containing):
personal
adl
mailbox
host
ccaddress (full cc: line, up to 1024 characters)
cc[] (returns an array of objects from the Cc line, containing):
personal
adl
mailbox
host
bccaddress (full bcc line, up to 1024 characters)
bcc[] (returns an array of objects from the Bcc line, containing):
personal
adl
mailbox
host
reply_toaddress (full reply_to: line, up to 1024 characters)
reply_to[] (returns an array of objects from the Reply_to line,
containing):
personal
adl
mailbox
host
senderaddress (full sender: line, up to 1024 characters)
sender[] (returns an array of objects from the sender line, containing):
personal
adl
mailbox
host
return_path (full return-path: line, up to 1024 characters)
return_path[] (returns an array of objects from the return_path line,
containing):
personal
adl
mailbox
host
udate (mail message date in unix time)
fetchfrom (from line formatted to fit <parameter>fromlength</parameter>
characters)
fetchsubject (subject line formatted to fit <parameter>subjectlength</parameter>
characters)
</literallayout>
</informalexample>
</para>
</refsect1>
</refentry>
<refentry id="function.imap-headers">
<refnamediv>
<refname>imap_headers</refname>
<refpurpose>
Returneaz� headers for all messages in a mailbox
</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>array</type><methodname>imap_headers</methodname>
<methodparam><type>int</type><parameter>imap_stream</parameter></methodparam>
</methodsynopsis>
<para>
Returneaz� an array of string formatted with header info. One
element per mail message.
</para>
</refsect1>
</refentry>
<refentry id="function.imap-last-error">
<refnamediv>
<refname>imap_last_error</refname>
<refpurpose>
This function returns the last IMAP error (if any) that occurred
during this page request
</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>string</type><methodname>imap_last_error</methodname>
<void/>
</methodsynopsis>
<para>
This function returns the full text of the last IMAP error
message that occurred on the current page. The error stack is
untouched; calling <function>imap_last_error</function>
subsequently, with no intervening errors, will return the same
error.
</para>
</refsect1>
</refentry>
<refentry id="function.imap-listmailbox">
<refnamediv>
<refname>imap_listmailbox</refname>
<refpurpose>Read the list of mailboxes</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>array</type><methodname>imap_listmailbox</methodname>
<methodparam><type>int</type><parameter>imap_stream</parameter></methodparam>
<methodparam><type>string</type><parameter>ref</parameter></methodparam>
<methodparam><type>string</type><parameter>pattern</parameter></methodparam>
</methodsynopsis>
<para>
Returneaz� an array containing the names of the mailboxes.
See <function>imap_getmailboxes</function> for a description
of <parameter>ref</parameter> and <parameter>pattern</parameter>.
</para>
<para>
<example>
<title><function>imap_listmailbox</function> example</title>
<programlisting role="php">
<![CDATA[
$mbox = imap_open("{your.imap.host}","username","password",OP_HALFOPEN)
or die("can't connect: ".imap_last_error());
$list = imap_listmailbox($mbox,"{your.imap.host}","*");
if(is_array($list)) {
reset($list);
while (list($key, $val) = each($list))
print imap_utf7_decode($val)."<br>\n";
} else
print "imap_listmailbox failed: ".imap_last_error()."\n";
imap_close($mbox);
]]>
</programlisting>
</example>
</para>
</refsect1>
</refentry>
<refentry id="function.imap-listsubscribed">
<refnamediv>
<refname>imap_listsubscribed</refname>
<refpurpose>List all the subscribed mailboxes</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>array</type><methodname>imap_listsubscribed</methodname>
<methodparam><type>int</type><parameter>imap_stream</parameter></methodparam>
<methodparam><type>string</type><parameter>ref</parameter></methodparam>
<methodparam><type>string</type><parameter>pattern</parameter></methodparam>
</methodsynopsis>
<para>
Returneaz� an array of all the mailboxes that you have
subscribed. This is almost identical to
<function>imap_listmailbox</function>, but will only return
mailboxes the user you logged in as has subscribed.
</para>
</refsect1>
</refentry>
<refentry id="function.imap-mail">
<refnamediv>
<refname>imap_mail</refname>
<refpurpose>
Send an email message
</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>string</type><methodname>imap_mail</methodname>
<methodparam><type>string</type><parameter>to</parameter></methodparam>
<methodparam><type>string</type><parameter>subject</parameter></methodparam>
<methodparam><type>string</type><parameter>message</parameter></methodparam>
<methodparam
choice="opt"><type>string</type><parameter>additional_headers</parameter></methodparam>
<methodparam
choice="opt"><type>string</type><parameter>cc</parameter></methodparam>
<methodparam
choice="opt"><type>string</type><parameter>bcc</parameter></methodparam>
<methodparam
choice="opt"><type>string</type><parameter>rpath</parameter></methodparam>
</methodsynopsis>
<para>
This function allows sending of emails with correct handling of Cc and Bcc
receivers.
The parameters to, cc and bcc are all strings and are all parsed as rfc822
address lists.
The receivers specified in bcc will get the mail, but are excluded from the
headers.
Use the rpath parameter to specify return path. This is useful when using php as
a mail client
for multiple users.
</para>
</refsect1>
</refentry>
<refentry id="function.imap-mail-compose">
<refnamediv>
<refname>imap_mail_compose</refname>
<refpurpose>
Create a MIME message based on given envelope and body sections
</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>string</type><methodname>imap_mail_compose</methodname>
<methodparam><type>array</type><parameter>envelope</parameter></methodparam>
<methodparam><type>array</type><parameter>body</parameter></methodparam>
</methodsynopsis>
<para>
</para>
<para>
<example>
<title><function>imap_mail_compose</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
$envelope["from"]="[EMAIL PROTECTED]";
$envelope["to"]="musone@darkstar";
$envelope["cc"]="[EMAIL PROTECTED]";
$part1["type"]=TYPEMULTIPART;
$part1["subtype"]="mixed";
$filename="/tmp/imap.c.gz";
$fp=fopen($filename,"r");
$contents=fread($fp,filesize($filename));
fclose($fp);
$part2["type"]=TYPEAPPLICATION;
$part2["encoding"]=ENCBINARY;
$part2["subtype"]="octet-stream";
$part2["description"]=basename($filename);
$part2["contents.data"]=$contents;
$part3["type"]=TYPETEXT;
$part3["subtype"]="plain";
$part3["description"]="description3";
$part3["contents.data"]="contents.data3\n\n\n\t";
$body[1]=$part1;
$body[2]=$part2;
$body[3]=$part3;
echo nl2br(imap_mail_compose($envelope,$body));
?>
]]>
</programlisting>
</example>
</para>
</refsect1>
</refentry>
<refentry id="function.imap-mail-copy">
<refnamediv>
<refname>imap_mail_copy</refname>
<refpurpose>Copy specified messages to a mailbox</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>int</type><methodname>imap_mail_copy</methodname>
<methodparam><type>int</type><parameter>imap_stream</parameter></methodparam>
<methodparam><type>string</type><parameter>msglist</parameter></methodparam>
<methodparam><type>string</type><parameter>mbox</parameter></methodparam>
<methodparam
choice="opt"><type>int</type><parameter>flags</parameter></methodparam>
</methodsynopsis>
<para>
Returneaz� &true; on success and &false; on error.
</para>
<para>
Copies mail messages specified by <parameter>msglist</parameter>
to specified mailbox. <parameter>msglist</parameter> is a range
not just message numbers (as described in
<ulink url="&url.rfc;rfc2060.html">RFC2060</ulink>).
</para>
<para>
Flags is a bitmask of one or more of
<itemizedlist>
<listitem>
<simpara>
CP_UID - the sequence numbers contain UIDS
</simpara>
</listitem>
<listitem>
<simpara>
CP_MOVE - Delete the messages from the current mailbox after
copying
</simpara>
</listitem>
</itemizedlist>
</para>
</refsect1>
</refentry>
<refentry id="function.imap-mail-move">
<refnamediv>
<refname>imap_mail_move</refname>
<refpurpose>Move specified messages to a mailbox</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>int</type><methodname>imap_mail_move</methodname>
<methodparam><type>int</type><parameter>imap_stream</parameter></methodparam>
<methodparam><type>string</type><parameter>msglist</parameter></methodparam>
<methodparam><type>string</type><parameter>mbox</parameter></methodparam>
<methodparam
choice="opt"><type>int</type><parameter>flags</parameter></methodparam>
</methodsynopsis>
<para>
Moves mail messages specified by <parameter>msglist</parameter>
to specified mailbox. <parameter>msglist</parameter> is a range
not just message numbers (as described in
<ulink url="&url.rfc;rfc2060.html">RFC2060</ulink>).
</para>
<para>
Flags is a bitmask and may contain the single option
<itemizedlist>
<listitem>
<simpara>
CP_UID - the sequence numbers contain UIDS
</simpara>
</listitem>
</itemizedlist>
</para>
<para>
Returneaz� &true; on success and &false; on error.
</para>
</refsect1>
</refentry>
<refentry id="function.imap-mailboxmsginfo">
<refnamediv>
<refname>imap_mailboxmsginfo</refname>
<refpurpose>Get information about the current mailbox</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>object</type><methodname>imap_mailboxmsginfo</methodname>
<methodparam><type>int</type><parameter>imap_stream</parameter></methodparam>
</methodsynopsis>
<para>
Returneaz� information about the current mailbox. Returneaz� &false; on
failure.
</para>
<para>
The <function>imap_mailboxmsginfo</function> function checks the
current mailbox status on the server. It is similar to
<function>imap_status</function>, but will additionally sum up the
size of all messages in the mailbox, which will take some additional
time to execute. It returns the information
in an object with following properties.
</para>
<para>
<table>
<title>Mailbox properties</title>
<tgroup cols="2">
<tbody>
<row>
<entry>Date</entry>
<entry>date of last change</entry>
</row>
<row>
<entry>Driver</entry>
<entry>driver</entry>
</row>
<row>
<entry>Mailbox</entry>
<entry>name of the mailbox</entry>
</row>
<row>
<entry>Nmsgs</entry>
<entry>number of messages</entry>
</row>
<row>
<entry>Recent</entry>
<entry>number of recent messages</entry>
</row>
<row>
<entry>Unread</entry>
<entry>number of unread messages</entry>
</row>
<row>
<entry>Deleted</entry>
<entry>number of deleted messages</entry>
</row>
<row>
<entry>Size</entry>
<entry>mailbox size</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<para>
<example>
<title><function>imap_mailboxmsginfo</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
$mbox = imap_open("{your.imap.host}INBOX","username", "password")
or die("can't connect: ".imap_last_error());
$check = imap_mailboxmsginfo($mbox);
if($check) {
print "Date: " . $check->Date ."<br>\n" ;
print "Driver: " . $check->Driver ."<br>\n" ;
print "Mailbox: " . $check->Mailbox ."<br>\n" ;
print "Messages: ". $check->Nmsgs ."<br>\n" ;
print "Recent: " . $check->Recent ."<br>\n" ;
print "Unread: " . $check->Unread ."<br>\n" ;
print "Deleted: " . $check->Deleted ."<br>\n" ;
print "Size: " . $check->Size ."<br>\n" ;
} else {
print "imap_check() failed: ".imap_last_error(). "<br>\n";
}
imap_close($mbox);
?>
]]>
</programlisting>
</example>
</para>
</refsect1>
</refentry>
<refentry id="function.imap-mime-header-decode">
<refnamediv>
<refname>imap_mime_header_decode</refname>
<refpurpose>Decode MIME header elements</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>array</type><methodname>imap_mime_header_decode</methodname>
<methodparam><type>string</type><parameter>text</parameter></methodparam>
</methodsynopsis>
<para>
<function>imap_mime_header_decode</function> function decodes
MIME message header extensions that are non ASCII text
(see <ulink url="&url.rfc;rfc2047.html">RFC2047</ulink>)
The decoded elements are returned in an array of objects,
where each object has two properties, "charset" & "text".
If the element hasn't been encoded, and in other words is in
plain US-ASCII,the "charset" property of that element is set to
"default".
</para>
<para>
<example>
<title><function>imap_mime_header_decode</function> example</title>
<programlisting role="php">
<![CDATA[
$text="=?ISO-8859-1?Q?Keld_J=F8rn_Simonsen?= <[EMAIL PROTECTED]>";
$elements=imap_mime_header_decode($text);
for($i=0;$i<count($elements);$i++) {
echo "Charset: {$elements[$i]->charset}\n";
echo "Text: {$elements[$i]->text}\n\n";
}
]]>
</programlisting>
</example>
</para>
<para>
In the above example we would have two elements, whereas the first
element had previously been encoded with ISO-8859-1, and the second
element would be plain US-ASCII.
</para>
</refsect1>
</refentry>
<refentry id="function.imap-msgno">
<refnamediv>
<refname>imap_msgno</refname>
<refpurpose>
This function returns the message sequence number for the given
UID
</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>int</type><methodname>imap_msgno</methodname>
<methodparam><type>int</type><parameter>imap_stream</parameter></methodparam>
<methodparam><type>int</type><parameter>uid</parameter></methodparam>
</methodsynopsis>
<para>
This function returns the message sequence number for the given
UID. It is the inverse of <function>imap_uid</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.imap-num-msg">
<refnamediv>
<refname>imap_num_msg</refname>
<refpurpose>
Gives the number of messages in the current mailbox
</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>int</type><methodname>imap_num_msg</methodname>
<methodparam><type>int</type><parameter>imap_stream</parameter></methodparam>
</methodsynopsis>
<para>
Return the number of messages in the current mailbox.
</para>
<para>
See also: <function>imap_num_recent</function> and
<function>imap_status</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.imap-num-recent">
<refnamediv>
<refname>imap_num_recent</refname>
<refpurpose>Gives the number of recent messages in current
mailbox</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>int</type><methodname>imap_num_recent</methodname>
<methodparam><type>int</type><parameter>imap_stream</parameter></methodparam>
</methodsynopsis>
<para>
Returneaz� the number of recent messages in the current mailbox.
</para>
<para>
See also: <function>imap_num_msg</function> and
<function>imap_status</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.imap-open">
<refnamediv>
<refname>imap_open</refname>
<refpurpose>Open an IMAP stream to a mailbox</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>int</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>flags</parameter></methodparam>
</methodsynopsis>
<para>
Returneaz� 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 not 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>
The options are a bit mask with one or more of the following:
<itemizedlist>
<listitem>
<simpara>
OP_READONLY - Open mailbox read-only
</simpara>
</listitem>
<listitem>
<simpara>
OP_ANONYMOUS - Dont use or update a
<filename>.newsrc</filename> for news (NNTP only)
</simpara>
</listitem>
<listitem>
<simpara>
OP_HALFOPEN - For IMAP and NNTP names, open a connection but
dont open a mailbox
</simpara>
</listitem>
<listitem>
<simpara>
CL_EXPUNGE - Expunge mailbox automatically upon mailbox close
</simpara>
</listitem>
</itemizedlist>
</para>
<para>
To connect to an IMAP server running on port 143 on the
local machine, do the following:
<informalexample>
<programlisting role="php">
<![CDATA[
$mbox = imap_open ("{localhost:143}INBOX", "user_id", "password");
]]>
</programlisting>
</informalexample>
To connect to a POP3 server on port 110 on the local server, use:
<informalexample>
<programlisting role="php">
<![CDATA[
$mbox = imap_open ("{localhost:110/pop3}INBOX", "user_id", "password");
]]>
</programlisting>
</informalexample>
To connect to an SSL IMAP or POP3 server, add /ssl after the protocol
specification:
<informalexample>
<programlisting role="php">
<![CDATA[
$mbox = imap_open ("{localhost:993/imap/ssl}INBOX", "user_id", "password");
]]>
</programlisting>
</informalexample>
To connect to an SSL IMAP or POP3 server with a self-signed
certificate, add /ssl/novalidate-cert after the protocol specification:
<informalexample>
<programlisting role="php">
<![CDATA[
$mbox = imap_open ("{localhost:995/pop3/ssl/novalidate-cert}", "user_id", "password");
]]>
</programlisting>
</informalexample>
To connect to an NNTP server on port 119 on the local server, use:
<informalexample>
<programlisting role="php">
<![CDATA[
$nntp = imap_open ("{localhost:119/nntp}comp.test", "", "");
]]>
</programlisting>
</informalexample>
To connect to a remote server replace "localhost" with the name
or the IP address of the server you want to connect to.
</para>
<para>
<example>
<title><function>imap_open</function> example</title>
<programlisting role="php">
<![CDATA[
$mbox = imap_open ("{your.imap.host:143}", "username", "password");
echo "<p><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 "<p><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>
<refentry id="function.imap-ping">
<refnamediv>
<refname>imap_ping</refname>
<refpurpose>Check if the IMAP stream is still active</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>int</type><methodname>imap_ping</methodname>
<methodparam><type>int</type><parameter>imap_stream</parameter></methodparam>
</methodsynopsis>
<para>
Returneaz� &true; if the stream is still alive, &false; otherwise.
</para>
<para>
<function>imap_ping</function> function pings the stream to see
it is still active. It may discover new mail; this is the
preferred method for a periodic "new mail check" as well as a
"keep alive" for servers which have inactivity timeout.
(As PHP scripts do not tend to run that long, i can hardly
imagine that this function will be usefull to anyone.)
</para>
</refsect1>
</refentry>
<refentry id='function.imap-popen'>
<refnamediv>
<refname>imap_popen</refname>
<refpurpose>
Open a persistant IMAP stream to a mailbox
</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>int</type><methodname>imap_popen</methodname>
<methodparam><type>string</type><parameter>mailbox</parameter></methodparam>
<methodparam><type>string</type><parameter>user</parameter></methodparam>
<methodparam><type>string</type><parameter>password</parameter></methodparam>
<methodparam
choice="opt"><type>int</type><parameter>options</parameter></methodparam>
</methodsynopsis>
<para>
&warn.undocumented.func;
</para>
</refsect1>
</refentry>
<refentry id="function.imap-qprint">
<refnamediv>
<refname>imap_qprint</refname>
<refpurpose>Convert a quoted-printable string to an 8 bit
string</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>string</type><methodname>imap_qprint</methodname>
<methodparam><type>string</type><parameter>string</parameter></methodparam>
</methodsynopsis>
<para>
Convert a quoted-printable string to an 8 bit string (according
to <ulink url="&url.rfc;rfc2045.html">RFC2045</ulink>, section
6.7).
</para>
<para>
Returneaz� an 8 bit (binary) string.
</para>
<para>
See also <function>imap_8bit</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.imap-renamemailbox">
<refnamediv>
<refname>imap_renamemailbox</refname>
<refpurpose>Rename an old mailbox to new mailbox</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>int</type><methodname>imap_renamemailbox</methodname>
<methodparam><type>int</type><parameter>imap_stream</parameter></methodparam>
<methodparam><type>string</type><parameter>old_mbox</parameter></methodparam>
<methodparam><type>string</type><parameter>new_mbox</parameter></methodparam>
</methodsynopsis>
<para>
This function renames on old mailbox to new mailbox (see
<function>imap_open</function> for the format of
<parameter>mbox</parameter> names).
</para>
<para>
Returneaz� &true; on success and &false; on error.
</para>
<para>
See also <function>imap_createmailbox</function>,
<function>imap_deletemailbox</function>, and
<function>imap_open</function> for the format of
<parameter>mbox</parameter>.
</para>
</refsect1>
</refentry>
<refentry id="function.imap-reopen">
<refnamediv>
<refname>imap_reopen</refname>
<refpurpose>Reopen IMAP stream to new mailbox</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>int</type><methodname>imap_reopen</methodname>
<methodparam><type>int</type><parameter>imap_stream</parameter></methodparam>
<methodparam><type>string</type><parameter>mailbox</parameter></methodparam>
<methodparam
choice="opt"><type>string</type><parameter>flags</parameter></methodparam>
</methodsynopsis>
<para>
This function reopens the specified stream to a new mailbox on
an IMAP or NNTP server.
</para>
<para>
The options are a bit mask with one or more of the following:
<itemizedlist>
<listitem>
<simpara>
OP_READONLY - Open mailbox read-only
</simpara>
</listitem>
<listitem>
<simpara>
OP_ANONYMOUS - Dont use or update a
<filename>.newsrc</filename> for news (NNTP only)
</simpara>
</listitem>
<listitem>
<simpara>
OP_HALFOPEN - For IMAP and NNTP names, open a connection but
dont open a mailbox.
</simpara>
</listitem>
<listitem>
<simpara>
CL_EXPUNGE - Expunge mailbox automatically upon mailbox close
(see also <function>imap_delete</function> and
<function>imap_expunge</function>)
</simpara>
</listitem>
</itemizedlist>
</para>
<para>
Returneaz� &true; on success and &false; on error.
</para>
</refsect1>
</refentry>
<refentry id="function.imap-rfc822-parse-adrlist">
<refnamediv>
<refname>imap_rfc822_parse_adrlist</refname>
<refpurpose>Parses an address string</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>array</type><methodname>imap_rfc822_parse_adrlist</methodname>
<methodparam><type>string</type><parameter>address</parameter></methodparam>
<methodparam><type>string</type><parameter>default_host</parameter></methodparam>
</methodsynopsis>
<para>
This function parses the address string as defined in
<ulink url="&url.rfc;rfc2822.html">RFC2822</ulink> and
for each address, returns an array of objects.
The objects properties are:
</para>
<para>
<itemizedlist>
<listitem>
<simpara>
mailbox - the mailbox name (username)
</simpara>
</listitem>
<listitem>
<simpara>
host - the host name
</simpara>
</listitem>
<listitem>
<simpara>
personal - the personal name
</simpara>
</listitem>
<listitem>
<simpara>
adl - at domain source route
</simpara>
</listitem>
</itemizedlist>
</para>
<para>
<example>
<title><function>imap_rfc822_parse_adrlist</function> example</title>
<programlisting role="php">
<![CDATA[
$address_string = "Hartmut Holzgraefe <[EMAIL PROTECTED]>,
[EMAIL PROTECTED], root";
$address_array = imap_rfc822_parse_adrlist($address_string,"somedomain.net");
if(! is_array($address_array)) die("somethings wrong\n");
reset($address_array);
while(list($key,$val)=each($address_array)){
print "mailbox : ".$val->mailbox."<br>\n";
print "host : ".$val->host."<br>\n";
print "personal: ".$val->personal."<br>\n";
print "adl : ".$val->adl."<p>\n";
}
]]>
</programlisting>
</example>
</para>
</refsect1>
</refentry>
<refentry id="function.imap-rfc822-parse-headers">
<refnamediv>
<refname>imap_rfc822_parse_headers</refname>
<refpurpose>Parse mail headers from a string</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>object</type><methodname>imap_rfc822_parse_headers</methodname>
<methodparam><type>string</type><parameter>headers</parameter></methodparam>
<methodparam
choice="opt"><type>string</type><parameter>defaulthost</parameter></methodparam>
</methodsynopsis>
<para>
This function returns an object of various header elements,
similar to <function>imap_header</function>, except without the
flags and other elements that come from the IMAP server.
</para>
</refsect1>
</refentry>
<refentry id="function.imap-rfc822-write-address">
<refnamediv>
<refname>imap_rfc822_write_address</refname>
<refpurpose>
Returneaz� a properly formatted email address given the mailbox,
host, and personal info.
</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>string</type><methodname>imap_rfc822_write_address</methodname>
<methodparam><type>string</type><parameter>mailbox</parameter></methodparam>
<methodparam><type>string</type><parameter>host</parameter></methodparam>
<methodparam><type>string</type><parameter>personal</parameter></methodparam>
</methodsynopsis>
<para>
Returneaz� a properly formatted email address as defined in
<ulink url="&url.rfc;rfc2822.html">RFC2822</ulink>
given the mailbox, host, and personal info.
</para>
<para>
<example>
<title><function>imap_rfc822_write_address</function> example</title>
<programlisting role="php">
<![CDATA[
print imap_rfc822_write_address("hartmut","cvs.php.net","Hartmut Holzgraefe")."\n";
]]>
</programlisting>
</example>
</para>
</refsect1>
</refentry>
<refentry id="function.imap-scanmailbox">
<refnamediv>
<refname>imap_scanmailbox</refname>
<refpurpose>
Read the list of mailboxes, takes a string to search for in the
text of the mailbox
</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>array</type><methodname>imap_scanmailbox</methodname>
<methodparam><type>int</type><parameter>imap_stream</parameter></methodparam>
<methodparam><type>string</type><parameter>ref</parameter></methodparam>
<methodparam><type>string</type><parameter>pattern</parameter></methodparam>
<methodparam><type>string</type><parameter>content</parameter></methodparam>
</methodsynopsis>
<para>
Returneaz� an array containing the names of the mailboxes that have
<parameter>content</parameter> in the text of the mailbox.
This function is similar to <function>imap_listmailbox</function>,
but it will additionally check for the presence of the string
<parameter>content</parameter> inside the mailbox data.
See <function>imap_getmailboxes</function> for a description
of <parameter>ref</parameter> and <parameter>pattern</parameter>.
</para>
</refsect1>
</refentry>
<refentry id="function.imap-search">
<refnamediv>
<refname>imap_search</refname>
<refpurpose>
This function returns an array of messages matching the given
search criteria
</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>array</type><methodname>imap_search</methodname>
<methodparam><type>int</type><parameter>imap_stream</parameter></methodparam>
<methodparam><type>string</type><parameter>criteria</parameter></methodparam>
<methodparam><type>int</type><parameter>flags</parameter></methodparam>
</methodsynopsis>
<para>
This function performs a search on the mailbox currently opened
in the given imap stream. <parameter>criteria</parameter> is a
string, delimited by spaces, in which the following keywords are
allowed. Any multi-word arguments (eg. FROM "joey smith") must be
quoted.
<itemizedlist>
<listitem>
<simpara>
ALL - return all messages matching the rest of the criteria
</simpara>
</listitem>
<listitem>
<simpara>
ANSWERED - match messages with the \\ANSWERED flag set
</simpara>
</listitem>
<listitem>
<simpara>
BCC "string" - match messages with "string" in the Bcc: field
</simpara>
</listitem>
<listitem>
<simpara>
BEFORE "date" - match messages with Date: before "date"
</simpara>
</listitem>
<listitem>
<simpara>
BODY "string" - match messages with "string" in the body of the message
</simpara>
</listitem>
<listitem>
<simpara>
CC "string" - match messages with "string" in the Cc: field
</simpara>
</listitem>
<listitem>
<simpara>
DELETED - match deleted messages
</simpara>
</listitem>
<listitem>
<simpara>
FLAGGED - match messages with the \\FLAGGED (sometimes
referred to as Important or Urgent) flag set
</simpara>
</listitem>
<listitem>
<simpara>
FROM "string" - match messages with "string" in the From: field
</simpara>
</listitem>
<listitem>
<simpara>
KEYWORD "string" - match messages with "string" as a keyword
</simpara>
</listitem>
<listitem>
<simpara>
NEW - match new messages
</simpara>
</listitem>
<listitem>
<simpara>
OLD - match old messages
</simpara>
</listitem>
<listitem>
<simpara>
ON "date" - match messages with Date: matching "date"
</simpara>
</listitem>
<listitem>
<simpara>
RECENT - match messages with the \\RECENT flag set
</simpara>
</listitem>
<listitem>
<simpara>
SEEN - match messages that have been read (the \\SEEN flag is set)
</simpara>
</listitem>
<listitem>
<simpara>
SINCE "date" - match messages with Date: after "date"
</simpara>
</listitem>
<listitem>
<simpara>
SUBJECT "string" - match messages with "string" in the Subject:
</simpara>
</listitem>
<listitem>
<simpara>
TEXT "string" - match messages with text "string"
</simpara>
</listitem>
<listitem>
<simpara>
TO "string" - match messages with "string" in the To:
</simpara>
</listitem>
<listitem>
<simpara>
UNANSWERED - match messages that have not been answered
</simpara>
</listitem>
<listitem>
<simpara>
UNDELETED - match messages that are not deleted
</simpara>
</listitem>
<listitem>
<simpara>
UNFLAGGED - match messages that are not flagged
</simpara>
</listitem>
<listitem>
<simpara>
UNKEYWORD "string" - match messages that do not have the
keyword "string"
</simpara>
</listitem>
<listitem>
<simpara>
UNSEEN - match messages which have not been read yet
</simpara>
</listitem>
</itemizedlist>
</para>
<para>
For example, to match all unanswered messages sent by Mom, you'd
use: "UNANSWERED FROM mom". Searches appear to be case
insensitive. This list of criteria is from a reading of the UW
c-client source code and may be uncomplete or
inaccurate (see also RFC2060, section 6.4.4).
</para>
<para>
Valid values for flags are SE_UID, which causes the returned
array to contain UIDs instead of messages sequence numbers.
</para>
</refsect1>
</refentry>
<refentry id='function.imap-setacl'>
<refnamediv>
<refname>imap_setacl</refname>
<refpurpose>
Sets the ACL for a giving mailbox
</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>int</type><methodname>imap_setacl</methodname>
<methodparam><type>int</type><parameter>stream_id</parameter></methodparam>
<methodparam><type>string</type><parameter>mailbox</parameter></methodparam>
<methodparam><type>string</type><parameter>id</parameter></methodparam>
<methodparam><type>string</type><parameter>rights</parameter></methodparam>
</methodsynopsis>
<para>
&warn.undocumented.func;
</para>
</refsect1>
</refentry>
<refentry id="function.imap-set-quota">
<refnamediv>
<refname>imap_set_quota</refname>
<refpurpose>Sets a quota for a given mailbox</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>int</type><methodname>imap_set_quota</methodname>
<methodparam><type>int</type><parameter>imap_stream</parameter></methodparam>
<methodparam><type>string</type><parameter>quota_root</parameter></methodparam>
<methodparam><type>int</type><parameter>quota_limit</parameter></methodparam>
</methodsynopsis>
<para>
Sets an upper limit quota on a per mailbox basis. This function
requires the <parameter>imap_stream</parameter> to have been opened
as the mail administrator account. It will not work if opened as
any other user.
</para>
<para>
This function is currently only available to users of the c-client2000
library.
</para>
<para>
<parameter>imap_stream</parameter> is the stream pointer returned from
a <function>imap_open</function> call. This stream must be opened as
the mail administrator, other wise this function will fail.
<parameter>quota_root</parameter> is the mailbox to have a quota set. This
should follow the IMAP standard format for a mailbox, 'user.name'.
<parameter>quota_limit</parameter> is the maximum size (in KB) for
the <parameter>quota_root</parameter>.
</para>
<para>
Returneaz� &true; on success and &false; on error.
</para>
<para>
<example>
<title><function>imap_set_quota</function> example</title>
<programlisting role="php">
<![CDATA[
$mbox = imap_open ("{your.imap.host:143}", "mailadmin", "password");
if(!imap_set_quota($mbox, "user.kalowsky", 3000)) {
print "Error in setting quota\n";
return;
}
imap_close($mbox);
]]>
</programlisting>
</example>
</para>
<para>
See also <function>imap_open</function>, <function>imap_set_quota</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.imap-setflag-full">
<refnamediv>
<refname>imap_setflag_full</refname>
<refpurpose>Sets flags on messages</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>string</type><methodname>imap_setflag_full</methodname>
<methodparam><type>int</type><parameter>stream</parameter></methodparam>
<methodparam><type>string</type><parameter>sequence</parameter></methodparam>
<methodparam><type>string</type><parameter>flag</parameter></methodparam>
<methodparam><type>string</type><parameter>options</parameter></methodparam>
</methodsynopsis>
<para>
This function causes a store to add the specified flag to the
flags set for the messages in the specified sequence.
</para>
<para>
The flags which you can set are "\\Seen", "\\Answered",
"\\Flagged", "\\Deleted", "\\Draft", and "\\Recent" (as defined
by RFC2060).
</para>
<para>
The options are a bit mask with one or more of the following:
<informalexample>
<literallayout>
ST_UID The sequence argument contains UIDs instead of
sequence numbers
</literallayout>
</informalexample>
</para>
<para>
<example>
<title><function>imap_setflag_full</function> example</title>
<programlisting role="php">
<![CDATA[
$mbox = imap_open("{your.imap.host:143}","username","password")
or die("can't connect: ".imap_last_error());
$status = imap_setflag_full($mbox,"2,5","\\Seen \\Flagged");
print gettype($status)."\n";
print $status."\n";
imap_close($mbox);
]]>
</programlisting>
</example>
</para>
</refsect1>
</refentry>
<refentry id="function.imap-sort">
<refnamediv>
<refname>imap_sort</refname>
<refpurpose>Sort an array of message headers</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>array</type><methodname>imap_sort</methodname>
<methodparam><type>int</type><parameter>stream</parameter></methodparam>
<methodparam><type>int</type><parameter>criteria</parameter></methodparam>
<methodparam><type>int</type><parameter>reverse</parameter></methodparam>
<methodparam><type>int</type><parameter>options</parameter></methodparam>
</methodsynopsis>
<para>
Returneaz� an array of message numbers sorted by the given
parameters.
</para>
<para>
<parameter>Reverse</parameter> is 1 for reverse-sorting.
</para>
<para>
Criteria can be one (and only one) of the following:
<informalexample>
<literallayout>
SORTDATE message Date
SORTARRIVAL arrival date
SORTFROM mailbox in first From address
SORTSUBJECT message Subject
SORTTO mailbox in first To address
SORTCC mailbox in first cc address
SORTSIZE size of message in octets
</literallayout>
</informalexample>
</para>
<para>
The flags are a bitmask of one or more of the following:
<informalexample>
<literallayout>
SE_UID Return UIDs instead of sequence numbers
SE_NOPREFETCH Don't prefetch searched messages.
</literallayout>
</informalexample>
</para>
</refsect1>
</refentry>
<refentry id="function.imap-status">
<refnamediv>
<refname>imap_status</refname>
<refpurpose>
This function returns status information on a mailbox other than
the current one
</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>object</type><methodname>imap_status</methodname>
<methodparam><type>int</type><parameter>imap_stream</parameter></methodparam>
<methodparam><type>string</type><parameter>mailbox</parameter></methodparam>
<methodparam><type>int</type><parameter>options</parameter></methodparam>
</methodsynopsis>
<para>
This function returns an object containing status
information. Valid flags are:
<itemizedlist>
<listitem>
<simpara>
SA_MESSAGES - set status->messages to the number of messages
in the mailbox
</simpara>
</listitem>
<listitem>
<simpara>
SA_RECENT - set status->recent to the number of recent
messages in the mailbox
</simpara>
</listitem>
<listitem>
<simpara>
SA_UNSEEN - set status->unseen to the number of unseen (new)
messages in the mailbox
</simpara>
</listitem>
<listitem>
<simpara>
SA_UIDNEXT - set status->uidnext to the next uid to be used in
the mailbox
</simpara>
</listitem>
<listitem>
<simpara>
SA_UIDVALIDITY - set status->uidvalidity to a constant that
changes when uids for the mailbox may no longer be valid
</simpara>
</listitem>
<listitem>
<simpara>
SA_ALL - set all of the above
</simpara>
</listitem>
</itemizedlist>
</para>
<para>
status->flags is also set, which contains a bitmask which can be
checked against any of the above constants.
</para>
<para>
<example>
<title><function>imap_status</function> example</title>
<programlisting role="php">
<![CDATA[
$mbox = imap_open("{your.imap.host}","username","password",OP_HALFOPEN)
or die("can't connect: ".imap_last_error());
$status = imap_status($mbox,"{your.imap.host}INBOX",SA_ALL);
if($status) {
print("Messages: ". $status->messages )."<br>\n";
print("Recent: ". $status->recent )."<br>\n";
print("Unseen: ". $status->unseen )."<br>\n";
print("UIDnext: ". $status->uidnext )."<br>\n";
print("UIDvalidity:". $status->uidvalidity)."<br>\n";
} else
print "imap_status failed: ".imap_last_error()."\n";
imap_close($mbox);
]]>
</programlisting>
</example>
</para>
</refsect1>
</refentry>
<refentry id="function.imap-subscribe">
<refnamediv>
<refname>imap_subscribe</refname>
<refpurpose>Subscribe to a mailbox</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>int</type><methodname>imap_subscribe</methodname>
<methodparam><type>int</type><parameter>imap_stream</parameter></methodparam>
<methodparam><type>string</type><parameter>mbox</parameter></methodparam>
</methodsynopsis>
<para>
Subscribe to a new mailbox.
</para>
<para>
Returneaz� &true; on success and &false; on error.
</para>
</refsect1>
</refentry>
<refentry id="function.imap-uid">
<refnamediv>
<refname>imap_uid</refname>
<refpurpose>
This function returns the UID for the given message sequence
number
</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>int</type><methodname>imap_uid</methodname>
<methodparam><type>int</type><parameter>imap_stream</parameter></methodparam>
<methodparam><type>int</type><parameter>msgno</parameter></methodparam>
</methodsynopsis>
<para>
This function returns the UID for the given message sequence
number. An UID is an unique identifier that will not change over
time while a message sequence number may change whenever the
content of the mailbox changes. This function is the inverse of
<function>imap_msgno</function>.
</para>
<note>
<para>
This is not supported by POP3 mailboxes.
</para>
</note>
</refsect1>
</refentry>
<refentry id="function.imap-undelete">
<refnamediv>
<refname>imap_undelete</refname>
<refpurpose>
Unmark the message which is marked deleted
</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>int</type><methodname>imap_undelete</methodname>
<methodparam><type>int</type><parameter>imap_stream</parameter></methodparam>
<methodparam><type>int</type><parameter>msg_number</parameter></methodparam>
</methodsynopsis>
<para>
This function removes the deletion flag for a specified message,
which is set by <function>imap_delete</function> or
<function>imap_mail_move</function>.
</para>
<para>
Returneaz� &true; on success and &false; on error.
</para>
</refsect1>
</refentry>
<refentry id="function.imap-unsubscribe">
<refnamediv>
<refname>imap_unsubscribe</refname>
<refpurpose>Unsubscribe from a mailbox</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>int</type><methodname>imap_unsubscribe</methodname>
<methodparam><type>int</type><parameter>imap_stream</parameter></methodparam>
<methodparam><type>string</type><parameter>mbox</parameter></methodparam>
</methodsynopsis>
<para>
Unsubscribe from a specified mailbox.
</para>
<para>
Returneaz� &true; on success and &false; on error.
</para>
</refsect1>
</refentry>
<refentry id="function.imap-utf7-decode">
<refnamediv>
<refname>imap_utf7_decode</refname>
<refpurpose>
Decodes a modified UTF-7 encoded string.
</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>string</type><methodname>imap_utf7_decode</methodname>
<methodparam><type>string</type><parameter>text</parameter></methodparam>
</methodsynopsis>
<para>
Decodes modified UTF-7 <parameter>text</parameter> into 8bit data.
</para>
<para>
Returneaz� the decoded 8bit data, or &false; if the input string was
not valid modified UTF-7. This function is needed to decode
mailbox names that contain international characters outside of
the printable ASCII range. The modified UTF-7 encoding is defined
in <ulink url="&url.rfc;rfc2060.html">RFC 2060</ulink>, section
5.1.3 (original UTF-7 was defned in <ulink
url="&url.rfc;rfc1642.html">RFC1642</ulink>).
</para>
</refsect1>
</refentry>
<refentry id="function.imap-utf7-encode">
<refnamediv>
<refname>imap_utf7_encode</refname>
<refpurpose>
Converts 8bit data to modified UTF-7 text.
</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>string</type><methodname>imap_utf7_encode</methodname>
<methodparam><type>string</type><parameter>data</parameter></methodparam>
</methodsynopsis>
<para>
Converts 8bit <parameter>data</parameter> to modified UTF-7
text. This is needed to encode mailbox names that contain
international characters outside of the printable ASCII
range. The modified UTF-7 encoding is defined in <ulink
url="&url.rfc;rfc2060.html">RFC 2060</ulink>, section 5.1.3
(original UTF-7 was defned in <ulink
url="&url.rfc;rfc1642.html">RFC1642</ulink>).
</para>
<para>
Returneaz� the modified UTF-7 text.
</para>
</refsect1>
</refentry>
<refentry id="function.imap-utf8">
<refnamediv>
<refname>imap_utf8</refname>
<refpurpose>
Converts text to UTF8
</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>string</type><methodname>imap_utf8</methodname>
<methodparam><type>string</type><parameter>text</parameter></methodparam>
</methodsynopsis>
<para>
Converts the given <parameter>text</parameter> to
UTF8 (as defined in
<ulink url="&url.rfc;rfc2044.html">RFC2044</ulink>).
</para>
</refsect1>
</refentry>
<refentry id='function.imap-thread'>
<refnamediv>
<refname>imap_thread</refname>
<refpurpose>
Return threaded by REFERENCES tree
</refpurpose>
</refnamediv>
<refsect1>
<title>Descriere</title>
<methodsynopsis>
<type>int</type><methodname>imap_thread</methodname>
<methodparam><type>int</type><parameter>stream_id</parameter></methodparam>
<methodparam
choice="opt"><type>int</type><parameter>flags</parameter></methodparam>
</methodsynopsis>
<para>
&warn.undocumented.func;
</para>
</refsect1>
</refentry>
</reference>
<!-- 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
-->
