發行項
09/24/2010

xp_readmail (Transact-SQL)

從 SQL Mail 收件匣中讀取郵件訊息。sp_processmail 利用這個程序來處理 SQL Mail 收件匣中的所有郵件。

[!附註]

未來的 Microsoft SQL Server 版本將移除這項功能。請避免在新的開發工作中使用這項功能，並規劃修改目前使用這項功能的應用程式。

語法

xp_readmail [ [ @msg_id= ] 'message_id' ]
     [ , [ @type= ] 'type' [ OUTPUT ] ] 
     [ , [ @peek= ] 'peek' ]
     [ , [ @suppress_attach= ] 'suppress_attach' ]
     [ , [ @originator= ] 'sender' OUTPUT ]
     [ , [ @subject= ] 'subject' OUTPUT ]
     [ , [ @message= ] 'message' OUTPUT ]
     [ , [ @recipients= ] 'recipients [ ;...n ]' OUTPUT ]
     [ , [ @cc_list= ] 'copy_recipients [ ;...n ]' OUTPUT ]
     [ , [ @bcc_list= ] 'blind_copy_recipients [ ;...n ]' OUTPUT ]
     [ , [ @date_received= ] 'date' OUTPUT ]
     [ , [ @unread= ] 'unread_value' OUTPUT ]
     [ , [ @attachments= ] 'attachments [ ;...n ]' OUTPUT ])
     [ , [ @skip_bytes= ] bytes_to_skip OUTPUT ]
     [ , [ @msg_length= ] length_in_bytes OUTPUT ]
     [ , [ @originator_address= ] 'sender_address' OUTPUT ] ]

引數

[@msg_id = ] 'message_id'
這是要讀取的訊息識別碼。message_id 是 varchar(255)，沒有預設值。
[@type = ] 'type'
這是要根據 MAPI 定義傳回的訊息類型：

IP[ M|C ].Vendorname.subclass

如果用在輸入上，必須定義特定訊息的類型；如果 message_id 是 NULL 時，輸入就會忽略 type。type 是 varchar(255)，預設值是 NULL。SQL Mail 支援訊息類型 IPM 和 IPC。
OUTPUT
當指定這個引數時，它會將指定參數的值放在輸出參數中。
[@peek = ] 'peek'
這是指 SQL Server 是否傳回郵件的訊息，不會將郵件狀態改成已讀取。peek 是 varchar(5)，預設值是 FALSE。如果設為 FALSE，就會將郵件當作已讀取來處理。如果設為 TRUE，就會將郵件當作尚未讀取來處理。
[@suppress_attach = ] 'suppress_attach'
這是指是否抑制郵件附加檔案。suppress_attach 是 varchar(255)，預設值是 FALSE。如果設為 TRUE，SQL Server 可防止在 xp_readmail 讀取含附加檔案的訊息時建立暫存檔。如果設為 FALSE，當讀取含附加檔案的訊息時，就不會防止建立暫存檔。
[@originator = ] 'sender'
這是指傳回的郵件寄件者。sender是 varchar(255)，沒有預設值。
[@subject = ] 'subject'
這是指傳回的郵件訊息主旨。subject 是 varchar(255)，沒有預設值。
[@message=] 'message'
這是指郵件訊息的傳回主體或實際文字。message 是 text，沒有預設值。
[@recipients=] 'recipients [ ;...n] '
這是要傳回的郵件訊息的收件者清單 (用分號分隔)。收件者的名稱用分號 (;) 分隔。recipient_list 是 varchar(255)，沒有預設值。
[@cc_list = ] 'copy_recipients [ ;...n] '
這是要傳回的郵件訊息之 [副本:] 欄位中的收件者清單 (用分號分隔)。收件者的名稱用分號 (;) 分隔。cc_list 是 varchar(255)，沒有預設值。
[@bcc_list = ] 'blind_copy_recipients[ ;...n] '
這是要傳回的郵件訊息之 [密件副本:] 欄位中的收件者清單 (用分號分隔)。收件者的名稱用分號 (;) 分隔。bcc_list 是 varchar(255)，沒有預設值。如果電子郵件伺服器未提供 BCC 欄位的值，blind_copy_recipients 便是空的。
[@date_received = ] 'date'
這是郵件訊息的傳回日期。date 是 varchar(255)，沒有預設值。
[@unread = ] 'unread_value'
這是指先前未讀取 (true) 或已讀取 (false) 的訊息。unread_value 是 varchar(5)，預設值為 TRUE。
[@attachments = ] 'attachments [ ;... n] '
這是傳回的訊息郵件附加檔案暫存路徑清單 (用分號分隔)。各個暫存路徑用分號 (;) 分隔。attachments 是 varchar(255)，沒有預設值。
[@skip_bytes = ] bytes_to_skipOUTPUT
如果所傳遞的輸入值不是 0，這個參數會指定在略過多少位元組之後，便將訊息的下 255 個位元組 (最大值) 讀入 body_of_message 輸出參數。當使用 bytes_to_skip 時，body_of_message 包括訊息的下一部分，bytes_to_skip 會傳回訊息內的下一個起點 (上一個 bytes_to_skip 加上 message 的長度)。bytes_to_skip 是 int，預設值是 0。
[@msg_length = ] length_in_bytesOUTPUT
這是訊息的總長度 (以位元組為單位)。當在預存程序中搭配 bytes_to_skip 使用時，這個參數可用來每次讀取 255 個位元組。length_in_bytes 是 int。
[@originator_address = ] 'sender_address'
這是已解析的郵件訊息發起者郵件地址。sender_address 是 varchar(255)，沒有預設值。

傳回碼值

0 (成功) 或 1 (失敗)

結果集

xp_readmail 會傳回含下列資料行的結果集。

資料行名稱	描述
Originator	電子郵件訊息的寄件者
Date Received	電子郵件訊息的接收日期
Recipients	訊息所送往的人員
CC List	在電子郵件訊息 [副本:] 列中的人員
BCC List	電子郵件訊息「密件副本」欄位上的人員
Subject	電子郵件訊息的主旨
Message	訊息主體 (文字)
Unread	是否尚未讀取這則訊息
Attachments	訊息的任何附加檔案
Message ID	Message ID
Type	訊息類型

備註

除了無效參數，任何失敗都會記錄到 Microsoft Windows 應用程式記錄檔中。

您可以利用兩種方式來使用 xp_readmail：

將收件匣中的所有訊息當作結果集傳回用戶端。
從收件匣中讀取單一訊息。

若要將收件匣中的內容當作結果集傳回用戶端，請勿提供任何輸入參數。

將 suppress_attach 參數的預設值改成 TRUE 失敗，附加檔案可能會出現兩個安全性問題。

首先，如果兩個不同的使用者共用相同的暫存目錄，且登入相同的電腦，他們將能夠檢視彼此的附加檔案。您可以檢閱 attachments 輸出變數來判斷附加檔案的儲存位置，以及兩位使用者是否共用相同的暫存目錄。
其次，xp_deletemail 並不會刪除這些附加檔案，因此，您必須手動刪除每個附加檔案。

若要從收件匣中讀取單一訊息，請將 xp_findnextmsg 傳回的有效 message_id 當作輸入參數提供給 xp_readmail。您可以指定 peek 和 suppress_attach 作為輸入參數來控制讀取訊息的方式。當以這個方法來使用 peek 和 suppress_attach 時，所有其他參數都是選擇性的輸出參數，其中包含要讀取訊息中的特定資訊。

您可以執行下列命令來檢視利用 xp_findnextmsg 作為 xp_readmail 之輸入參數的範例：

sp_helptext 'sp_processmail';

當利用 xp_readmail 來讀取單一訊息時，它可以讀取區段中長度超出 255 個位元組的訊息文字。請利用 length_in_bytes 來讀取區段中長度超出 255 個位元組的訊息文字。同時利用 length_in_bytes 來作為輸入和輸出參數，可讓您編寫迴圈來處理整個訊息文字。下列程式碼顯示這樣的迴圈範例，其中假設將 message_id 設為 xp_findnextmsg 傳回的有效訊息識別碼。

USE master;
GO

-- Set up variables.

DECLARE @status INT,
        @message_part VARCHAR(255),
        @msg_id VARCHAR(255),
        @message_length INT,
        @skip_bytes INT,
        @message VARCHAR(MAX) ;

-- Find the next message

EXEC @status = dbo.xp_findnextmsg
     @msg_id = @msg_id OUTPUT ;


-- If xp_findnextmsg completed successfully and
-- there is a message in the inbox, read the message.

IF (@status = 0  AND @msg_id IS NOT NULL)
BEGIN
   WHILE (1=1)
   BEGIN
        EXEC @status = dbo.xp_readmail
             @msg_id = @msg_id,
             @msg_length = @message_length OUTPUT,
             @skip_bytes = @skip_bytes OUTPUT,
             @message = @message_part OUTPUT ;

        IF @status <> 0 BREAK ;

        SET @message = ISNULL(@message, '') + @message_part ;

        PRINT @message_length ;
        PRINT @skip_bytes;

        IF @message_length = @skip_bytes BREAK ;

    END ;
    
    IF @status = 0
    BEGIN
       SELECT 'Message ID' = @msg_id, 'Message Body' = @message ;
    END ;
    ELSE
        SELECT 'Could not read message.' ;
END;

GO

權限

需要系統管理員 (sysadmin) 固定伺服器角色中的成員資格，但是 EXECUTE 權限可以授與其他使用者。不過，基於安全性的考量，建議您將這個預存程序的權限限制在系統管理員 (sysadmin) 固定伺服器角色的成員。

範例

下列範例會在讀取訊息時傳回狀態。在這個範例中，xp_findnextmsg 中的訊息識別碼值放在本機變數 @message\_id 中，並傳給 xp_readmail。

USE master ;
GO

DECLARE @status INT,
    @msg_id VARCHAR(255),
    @originator VARCHAR(255),
    @cc_list VARCHAR(255),
    @subject VARCHAR(255),
    @query VARCHAR(8000);


-- Find the next message

EXEC @status = dbo.xp_findnextmsg
     @msg_id = @msg_id OUTPUT ;


-- If xp_findnextmsg completed successfully and
-- there is a message in the inbox, read the message.

IF (@status = 0  AND @msg_id IS NOT NULL)
BEGIN
    EXEC @status = dbo.xp_readmail
        @msg_id = @msg_id,
        @originator = @originator OUTPUT,
        @cc_list = @cc_list OUTPUT,
        @subject = @subject OUTPUT,
        @message = @query OUTPUT,
        @peek = 'TRUE',
        @suppress_attach = 'TRUE'

END;
GO