imap_getmailboxes

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_getmailboxes — 讀取信箱列表，返回每個信箱的詳細資訊

說明

imap_getmailboxes(IMAP\Connection $imap, 字串 $reference, 字串 $pattern): 陣列|false

取得信箱的資訊。

參數

imap

一個 IMAP\Connection 實例。

reference

參數 reference 通常應為伺服器規格，如 imap_open() 中所述。

警告

除非停用 imap.enable_insecure_rsh，否則將不受信任的資料傳遞給此參數是*不安全的*。

pattern

指定在信箱階層結構中開始搜尋的位置。

您可以傳遞兩個特殊字元作為 pattern 的一部分：'*' 和 '%'。'*' 表示返回所有信箱。如果您將 pattern 傳遞為 '*'，您將獲得整個信箱階層結構的清單。'%' 表示僅返回目前層級。以 '%' 作為 pattern 參數將僅返回頂層信箱；在 UW_IMAPD 上使用 '~/mail/%' 將返回 ~/mail 目錄中的每個信箱，但不返回該目錄子資料夾中的任何信箱。

返回值

返回一個包含信箱資訊的物件陣列。每個物件都具有屬性 name，指定信箱的全名；delimiter，它是此信箱所在階層結構部分的階層結構分隔符號；以及 attributes。Attributes 是一個位元遮罩，可以針對以下內容進行測試：

LATT_NOINFERIORS - 此信箱不包含，且可能不包含任何「子項」（在此信箱下沒有其他信箱）。呼叫 imap_createmailbox() 在此信箱上將無法運作。
LATT_NOSELECT - 這只是一個容器，而不是信箱 - 您無法開啟它。
LATT_MARKED - 此信箱已標記。這表示自上次檢查以來，它可能包含新訊息。並非所有 IMAP 伺服器都提供此功能。
LATT_UNMARKED - 此信箱未標記，不包含新訊息。如果提供了 MARKED 或 UNMARKED，則可以假設 IMAP 伺服器支援此信箱的此功能。
LATT_REFERRAL - 此容器具有指向遠端信箱的參照。
LATT_HASCHILDREN - 此信箱具有可選的子項。
LATT_HASNOCHILDREN - 此信箱沒有可選的子項。

失敗時，該函數返回 false。

更新日誌

版本	說明
8.1.0	`imap` 參數現在需要 IMAP\Connection 實例；先前需要有效的 `imap` 資源。

範例

範例 #1 imap_getmailboxes() 範例

<?php
$mbox = imap_open("{imap.example.org}", "username", "password", OP_HALFOPEN)
 or die("無法連線: " . imap_last_error());

$list = imap_getmailboxes($mbox, "{imap.example.org}", "*");
if (is_array($list)) {
 foreach ($list as $key => $val) {
 echo "($key) ";
 echo imap_utf7_decode($val->name) . ",";
 echo "'" . $val->delimiter . "',";
 echo $val->attributes . "<br />\n";
 }
} else {
 echo "imap_getmailboxes 失敗: " . imap_last_error() . "\n";
}

imap_close($mbox);
?>

另請參閱

imap_getsubscribed() - 列出所有已訂閱的信箱

發現問題了嗎？

瞭解如何改進此頁面 • 提交 Pull Request • 回報錯誤

＋新增註釋

使用者貢獻的註釋 3 則註釋

向上

向下

Mohamed Abbas mabbas_xyz at yahoo dot com ¶

18 年前

我目前正在開發一個簡單的 IMAP 用戶端，當我呼叫 imap_getmailboxes() 時，我在信箱物件的 attributes 屬性中收到不同的值，問題是我如何操作這些屬性以獲得有意義的值，
如果您努力尋找此問題的解決方案，您將
找不到任何有用的文件來解決這個問題，讓我們仔細看看這個問題。

當我針對不同的 IMAP 伺服器呼叫 imap_getmailboxes() 時，我得到以下屬性值

[attributes] => 9
[attributes] => 1
[attributes] => 64
[attributes] => 32
[attributes] => 40

文件告訴我們，我們要根據四個常數檢查這些屬性，這些常數是

LATT_NOINFERIORS
LATT_NOSELECT
LATT_MARKED
LATT_UNMARKED

這些常數的值為

LATT_NOINFERIORS = 1
LATT_NOSELECT = 2
LATT_MARKED = 4
LATT_UNMARKED = 8

您可以透過 echo 指令顯示每個常數的值來得到這個結果，但可惜的是，文件並沒有說明如何使用這些常數來檢查屬性。經過長時間的搜尋，我在 c-client 的原始碼中找到了答案。
(您可以從 ftp://ftp.cac.washington.edu/imap/ 取得原始碼)
在 \src\c-client 資料夾下，您可以找到 mail.h 檔，打開它，您會看到以下內容：

/* 階層中的終端節點 */
#define LATT_NOINFERIORS (long) 0x1
/* 名稱無法選取 */
#define LATT_NOSELECT (long) 0x2
/* 自上次存取後已變更 */
#define LATT_MARKED (long) 0x4
/* 自上次變更後已存取 */
#define LATT_UNMARKED (long) 0x8
/* 名稱具有指向遠端信箱的參考 */
#define LATT_REFERRAL (long) 0x10
/* 具有可選取的子項目 */
#define LATT_HASCHILDREN (long) 0x20
/* 沒有可選取的子項目 */
#define LATT_HASNOCHILDREN (long) 0x40

如您所見，這裡是我們原先的四個常數，以及另外三個常數：

LATT_REFERRAL
LATT_HASCHILDREN
LATT_HASNOCHILDREN

那麼，這三個屬性的值是多少呢？
LATT_REFERRAL 0x10 = 二進位制的 00010000，位元遮罩值為 2^4 = 16，依此類推，或者簡單地 echo 這個常數即可取得其值。因此：

LATT_REFERRAL = 16
LATT_HASCHILDREN = 32
LATT_HASNOCHILDREN = 64

最後，完整的常數列表如下：
LATT_NOINFERIORS = 1
LATT_NOSELECT = 2
LATT_MARKED = 4
LATT_UNMARKED = 8
LATT_REFERRAL = 16
LATT_HASCHILDREN = 32
LATT_HASNOCHILDREN = 64

好的，讓我們回到屬性。
[attributes] => 9
[attributes] => 1
[attributes] => 64
[attributes] => 32
[attributes] => 40

[attributes] => 9  這表示它是 LATT_UNMARKED 和 LATT_NOINFERIORS，1+8 =9

[attributes] => 1  這表示 LATT_NOINFERIORS

[attributes] => 64 這表示 LATT_HASNOCHILDREN

[attributes] => 32 這表示 LATT_HASCHILDREN

[attributes] => 40 這表示 LATT_HASCHILDREN 和 LATT_UNMARKED，32+8=40

這就像 Linux 的檔案權限，7 代表讀取、寫入和執行，4+2+1，讀取=4，寫入=2，執行=1

這就是我的發現，希望這能有所幫助。

Mohamed Abbas
Nileweb Egypt

向上

向下

foom at fuhm dot NO_supercalifragilisticexpialidocious_SPAM dot net ¶

23 年前

這份文件中，信箱屬性的列表非常容易誤導。尤其是 noinferiors 的解釋是錯誤的。它並不表示信箱目前沒有子項目，而是指它*永遠*不能有子項目。此外，marked 和 unmarked 僅被 UW-IMAP 使用的說法也是不正確的。它們在官方 IMAP 規範中，並且至少也被 Courier-imap 使用。


然而，需要注意的一件事是，有些損壞的 IMAP 伺服器會在它們想表達目前沒有子項目的時候發送 \Noinferiors。


摘自 IMAP4rev1 規範 (RFC 2060)：
\Noinferiors


在此名稱下，不可能存在任何子階層；目前不存在子階層，且未來也無法建立。




\Noselect


無法使用此名稱作為可選取的信箱。


\Marked


信箱已被伺服器標記為「感興趣的」；該信箱可能包含自上次選取該信箱後新增的郵件。




\Unmarked


自上次選取該信箱後，信箱不包含任何其他郵件。

向上

向下

ad-rotator.com ¶

20 年前

如果您使用 print_r() 或 var_dump() 顯示物件，並且屬性顯示為整數，這些整數代表位元遮罩的常數。

1 LATT_NOINFERIORS
2 LATT_NOSELECT
4 LATT_MARKED
8 LATT_UNMARKED

＋新增註釋