xp_readmail (Transact-SQL)

Syntax

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 ] ]

Argumente

• [ @msg_id = ] 'message_id'
  Die ID der Nachricht, die gelesen werden soll. message_id ist vom Datentyp varchar(255) und hat keinen Standardwert.

• [ @type = ] 'type'
  Der Typ der zurückzugebenden Nachricht entsprechend der MAPI-Definition:

  IP[ M|C ].Vendorname.subclass

  Wenn dieses Argument für die Eingabe verwendet wird, muss damit der Typ für eine spezifische Nachricht definiert werden. type wird bei der Eingabe ignoriert, wenn message_id NULL ist. type ist vom Datentyp varchar(255) und hat den Standardwert NULL. SQL Mail unterstützt die Nachrichtentypen IPM und IPC.

• OUTPUT
  Wenn diese Option angegeben wird, wird der Wert des angegebenen Parameters in den Ausgabeparameter platziert.

• [ @peek = ] 'peek'
  Gibt an, ob SQL Server die E-Mail-Nachricht zurückgibt, ohne ihren Status in den Status einer gelesenen Nachricht zu ändern. peek ist vom Datentyp varchar(5) und hat den Standardwert FALSE. Bei FALSE wird die E-Mail so behandelt, als ob sie bereits gelesen wurde. Bei TRUE wird die E-Mail so behandelt, als ob sie noch nicht gelesen wurde.

• [ @suppress_attach = ] 'suppress_attach'
  Gibt an, ob E-Mail-Anlagen unterdrückt werden. suppress_attach ist vom Datentyp varchar(255) und hat den Standardwert FALSE. Bei TRUE verhindert SQL Server das Erstellen temporärer Dateien, wenn xp_readmail eine Nachricht mit Anlagen liest. Bei FALSE wird das Erstellen von temporären Dateien nicht verhindert, wenn Nachrichten mit Anlagen gelesen werden.

• [ @originator = ] 'sender'
  Der zurückgegebene Absender der Nachricht. senderist vom Datentyp varchar(255) und hat keinen Standardwert.

• [ @subject=] 'subject'
  Der zurückgegebene Betreff der E-Mail-Nachricht. subject ist vom Datentyp varchar(255) und hat keinen Standardwert.

• [ @message=] 'message'
  Der zurückgegebene Text (der tatsächliche Text) der E-Mail-Nachricht. message ist vom Datentyp text und hat keinen Standardwert.

• [ @recipients=] 'recipients [ ;... n] '
  Die durch Semikolons getrennte Liste der Empfänger für die zurückzugebende E-Mail-Nachricht. Die Empfängernamen sind durch ein Semikolon (;) getrennt. recipient_list ist vom Datentyp varchar(255) und hat keinen Standardwert.

• [ @cc_list = ] 'copy_recipients [ ;... n] '
  Die durch Semikolons getrennte Liste der Empfänger im CC-Feld für die zurückzugebende E-Mail-Nachricht. Die Empfängernamen sind durch ein Semikolon (;) getrennt. cc_list ist vom Datentyp varchar(255) und hat keinen Standardwert.

• [ @bcc_list = ] 'blind_copy_recipients[ ;... n] '
  Die durch Semikolons getrennte Liste der Empfänger im BCC-Feld für die zurückzugebende E-Mail-Nachricht. Die Empfängernamen sind durch ein Semikolon (;) getrennt. bcc_list ist vom Datentyp varchar(255) und hat keinen Standardwert. Wenn der E-Mail-Server keinen Wert für das BCC-Feld bereitstellt, ist blind_copy_recipients leer.

• [ @date_received = ] 'date'
  Das zurückgegebene Datum der E-Mail-Nachricht. date ist vom Datentyp varchar(255) und hat keinen Standardwert.

• [ @unread = ] 'unread_value'
  Gibt an, ob eine Nachricht zuvor ungelesen (true) war oder ob dies nicht der Fall war (false). unread_value ist vom Datentyp varchar(5) und hat den Standardwert TRUE.

• [ @attachments = ] 'attachments [ ;... n] '
  Die durch Semikolons getrennte Liste der zurückzugebenden temporären Pfade der E-Mail-Anlagen für die Nachricht. Die temporären Pfade sind durch ein Semikolon (;) getrennt. attachments ist vom Datentyp varchar(255) und hat keinen Standardwert.

• [ @skip_bytes = ] bytes_to_skipOUTPUT
  Wenn ein anderer Wert als 0 für diese Eingabe übergeben wird, gibt dieser Parameter die Anzahl der Bytes an, die vor dem Einlesen der nächsten (maximal) 255 Bytes der Nachricht in den body_of_message-Ausgabeparameter ausgelassen werden. Wenn bytes_to_skip verwendet wird, enthält body_of_message den nächsten Teil der Nachricht, und bytes_to_skip wird mit dem nächsten Startpunkt innerhalb der Nachricht zurückgegeben (die vorherigen Bytes gemäß bytes_to_skip plus die Länge von message). bytes_to_skip ist vom Datentyp int und hat den Standardwert 0.

• [ @msg_length = ] length_in_bytesOUTPUT
  Die Gesamtlänge der Nachricht in Bytes. Bei Verwendung mit bytes_to_skip in einer gespeicherten Prozedur ermöglicht es dieser Parameter, Nachrichten in Segmenten von 255 Bytes zu lesen. length_in_bytes ist vom Datentyp int.

• [ @originator_address = ] 'sender_address'
  Die aufgelöste E-Mail-Adresse des Absenders der E-Mail-Nachricht. sender_address ist vom Datentyp varchar(255) und hat keinen Standardwert.

Rückgabecodewerte

0 (Erfolg) oder 1 (Fehler)

Resultsets

xp_readmail gibt ein Resultset mit den folgenden Spalten zurück.

Hinweise

Jeder Fehler außer einem ungültigen Parameter wird im Microsoft Windows-Anwendungsprotokoll aufgezeichnet.

Es gibt zwei Verwendungsmöglichkeiten für xp_readmail:

• Zurückgeben aller Nachrichten im Posteingang in Form eines Resultsets an den Client

• Lesen einer einzelnen Nachricht im Posteingang

Wenn der Inhalt des Posteingangs als Resultset an den Client zurückgegeben werden soll, dürfen Sie keine Eingabeparameter angeben.

Fehler beim Ändern des Standardwertes für den suppress_attach-Parameter in TRUE führen zu zwei möglichen Sicherheitsrisiken im Hinblick auf Anlagen.

• Wenn zwei verschiedene Benutzer dasselbe temporäre Verzeichnis gemeinsam verwenden und sich an demselben Computer anmelden, können sie die Anlagen des jeweils anderen Benutzers anzeigen. Mithilfe der attachments-Ausgabevariablen können Sie bestimmen, wo Anlagen gespeichert werden und ob zwei Benutzer dasselbe temporäre Verzeichnis gemeinsam verwenden können.

• Mit xp_deletemail werden diese Anlagen nicht gelöscht, jede Anlage muss daher manuell gelöscht werden.

Zum Lesen einer einzelnen Nachricht im Posteingang geben Sie einen gültigen von xp_findnextmsg zurückgegebenen message_id-Wert als Eingabeparameter für xp_readmail an. Sie können peek und suppress_attach als Eingabeparameter angeben, um zu steuern, wie die Nachricht gelesen wird. Bei Verwendung von peek und suppress_attach mit dieser Methode sind alle anderen Parameter optionale Ausgabeparameter, die bestimmte Informationen zu der zu lesenden Nachricht enthalten.

Führen Sie den folgenden Befehl aus, um ein Beispiel für die Verwendung von xp_findnextmsg als Eingabeparameter für xp_readmail anzuzeigen:

sp_helptext 'sp_processmail';

Beim Lesen einer einzelnen Nachricht kann xp_readmail Nachrichtentext, der länger als 255 Bytes ist, abschnittsweise lesen. Verwenden Sie length_in_bytes, um Nachrichtentext, der länger als 255 Bytes ist, abschnittsweise zu lesen. Die Verwendung von length_in_bytes sowohl als Eingabe- als auch Ausgabeparameter ermöglicht es, Code für eine Schleife zu schreiben, um den gesamten Nachrichtentext zu verarbeiten. Der folgende Code ist ein Beispiel für eine solche Schleife. Es wird dabei davon ausgegangen, dass message_id auf eine gültige, von xp_findnextmsg zurückgegebene Nachrichten-ID festgelegt ist.

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

Berechtigungen

Erfordert die Mitgliedschaft in der festen Serverrolle sysadmin, EXECUTE-Berechtigungen können jedoch auch anderen Benutzern erteilt werden. Aus Sicherheitsgründen wird jedoch empfohlen, die Berechtigungen für diese gespeicherte Prozedur auf Mitglieder der festen Serverrolle sysadmin zu beschränken.

Beispiele

Im folgenden Beispiel wird der Status beim Lesen einer Nachricht zurückgegeben. In diesem Beispiel wird der Wert einer Nachrichten-ID von xp_findnextmsg in der lokalen Variablen @message\_id gespeichert und an xp_readmail übergeben.

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

Siehe auch

Verweis