Article
03/31/2012

xp_readmail (Transact-SQL)

Lit un message provenant de la boîte de réception de SQL Mail. Cette procédure est utilisée par sp_processmail pour traiter toute la messagerie électronique de la boîte de réception de SQL Mail.

Notes

Cette fonctionnalité sera supprimée dans une prochaine version de Microsoft SQL Server. Évitez d'utiliser cette fonctionnalité dans de nouveaux travaux de développement et prévoyez de modifier les applications qui utilisent actuellement cette fonctionnalité.

Icône Lien de rubrique Conventions de la syntaxe de Transact-SQL

Syntaxe

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

Arguments

[ @msg_id = ] 'message_id'
ID du message à lire. message_id est de type varchar(255) et n'a pas de valeur par défaut.
[ @type = ] 'type'
Classe du message à renvoyer basé sur la définition de MAPI.

IP[ M|C ].Vendorname.subclass

Utilisé en entrée, cet argument doit définir le type d'un message spécifique ; type est ignoré en entrée si message_id a la valeur NULL. type est de type varchar(255), avec NULL comme valeur par défaut. SQL Mail prend en charge les messages de type IPM et IPC.
OUTPUT
Lorsqu'elle est précisée, cette option place la valeur du paramètre spécifié dans le paramètre de sortie.
[ @peek = ] 'peek'
Indique si SQL Server renvoie le message du courrier électronique sans modifier l'état de lecture du courrier. peek est de type varchar(5), avec FALSE comme valeur par défaut. S'il possède la valeur FALSE, le message électronique est traité comme étant lu. S'il possède la valeur TRUE, le message électronique est traité comme étant non lu.
[ @suppress_attach = ] 'suppress_attach'
Indique si les pièces jointes sont supprimées. suppress_attachest de type varchar(255), avec FALSE comme valeur par défaut. Avec la valeur TUE, SQL Server empêche la création de fichiers temporaires lorsque xp_readmail lit un message comportant des pièces-jointes. Avec la valeur FALSE, la création de fichiers temporaires n'est pas empêchée lorsque des messages dotés de pièces-jointes sont lus.
[ @originator = ] 'sender'
Expéditeur du courrier renvoyé. senderest de type varchar(255), sans valeur par défaut.
[ @subject = ] 'subject'
Objet du message électronique renvoyé. subject est de type varchar(255), sans valeur par défaut.
[ @message = ] 'message'
Message ou corps du texte du courrier renvoyé. message est de type text, sans valeur par défaut.
[ @recipients = ] 'recipients [ ;... n] '
Liste des destinataires, délimitée par des points-virgules, auxquels le message électronique est renvoyé. Les noms des destinataires sont séparés par un point-virgule (;). recipient_list est de type varchar(255), sans valeur par défaut.
[ @cc_list = ] 'copy_recipients [ ;... n] '
Liste des destinataires, délimitée par des points-virgules, figurant dans le champ Cc : du message électronique à renvoyer. Les noms des destinataires sont séparés par un point-virgule (;). cc_list est de type varchar(255), sans valeur par défaut.
[ @bcc_list = ] 'blind_copy_recipients[ ;... n] '
Liste des destinataires, délimitée par des points-virgules, figurant dans le champ Cci : du message électronique à renvoyer. Les noms des destinataires sont séparés par un point-virgule (;). bcc_list est de type varchar(255), sans valeur par défaut. Si le serveur de messagerie ne fournit pas de valeur pour le champ Cci, alors blind_copy_recipients est vide.
[ @date_received = ] 'date'
Date de retour du message électronique. date est de type varchar(255), sans valeur par défaut.
[ @unread = ] 'unread_value'
Indique si un message a été marqué comme non lu (true) ou non (false). unread_value est de type varchar(5), avec TRUE comme valeur par défaut.
[ @attachments = ] 'attachments [ ;... n] '
Liste, délimitée par des points-virgules, des chemins temporaires des pièces jointes au message. Les chemins d'accès temporaires sont séparés par un point-virgule (;). attachments est de type varchar(255), sans valeur par défaut.
[ @skip_bytes = ] bytes_to_skipOUTPUT
Si une valeur différente de 0 est transmise en entrée, ce paramètre spécifie le nombre d'octets à ignorer avant de lire les 255 octets (maximum) suivants du message dans le paramètre de sortie body_of_message. Lorsque bytes_to_skip est utilisé, body_of_message inclut la portion suivante du message et bytes_to_skip renvoie le point de départ suivant au sein du message (le premier paramètre bytes_to_skip auquel s'ajoute la longueur de message). bytes_to_skip est de type int, avec 0 comme valeur par défaut.
[ @msg_length = ] length_in_bytesOUTPUT
Renvoie la longueur totale du message, en octets. Lorsqu'il est utilisé avec bytes_to_skip dans une procédure stockée, ce paramètre permet la lecture des messages par blocs de 255 octets. length_in_bytes est de type int.
[ @originator_address = ] 'sender_address'
Adresse de messagerie résolue de l'auteur du message électronique. sender_address est de type varchar(255), sans valeur par défaut.

Valeurs des codes de retour

0 (succès) ou 1 (échec)

Jeux de résultats

xp_readmail renvoie un jeu de résultats comprenant ces colonnes.

Nom de colonne	Description
Originator	Expéditeur du message électronique
Date Received	Date de réception du message électronique
Recipients	Personnes auxquelles le message a été envoyé
CC List	Personnes figurant sur la ligne « Cc : » du message électronique
BCC List	Personnes figurant sur la ligne « Cci : » du message électronique
Objet	Objet du message électronique
Message	Corps du message (texte)
Unread	Indique si ce message est non lu
Attachments	Pièces éventuellement jointes au message
Message ID	Message ID
Type	Type du message

Notes

Tout échec à l'exception d'un paramètre non valide est consigné dans le journal des applications Microsoft Windows.

Il existe deux manières d'utiliser xp_readmail :

Renvoyer tous les messages de la boîte de réception comme jeu de résultats au client.
Lire un seul message de la boîte de réception.

Pour renvoyer le contenu de la boîte de réception comme jeu de résultats au client, ne fournissez aucun paramètre d'entrée.

Le fait de ne pas modifier la valeur par défaut du paramètre suppress_attach pour choisir TRUE soulève deux problèmes de sécurité potentiels relatifs aux pièces jointes.

Tout d’abord, si deux utilisateurs différents partagent le même dossier temporaire et se connectent sur le même ordinateur, chacun d’eux peut lire les pièces jointes de l’autre. Vous pouvez déterminer où les pièces jointes sont stockées et si deux utilisateurs partagent le même dossier temporaire en examinant la variable de sortie attachments.
Ensuite, xp_deletemail ne supprime pas ces pièces jointes, de sorte que vous devez le faire manuellement pour chacune.

Pour lire un seul message de la boîte de réception, fournissez un message_id valide renvoyé par xp_findnextmsg en tant que paramètre d'entrée de xp_readmail. Vous pouvez spécifier peek et suppress_attach en tant que paramètres d'entrée afin de contrôler la façon dont le message est lu. Si vous utilisez peek et suppress_attach avec cette méthode, tous les autres paramètres sont des paramètres de sortie facultatifs qui contiennent des informations spécifiques du message à lire.

Vous pouvez afficher un exemple de l'utilisation de xp_findnextmsg comme paramètre d'entrée pour xp_readmail en exécutant la commande suivante :

sp_helptext 'sp_processmail';

Lorsque xp_readmail est utilisé pour lire un seul message, il peut aussi lire le texte d'un message d'une longueur supérieure à 255 octets par section. Utilisez length_in_bytes pour lire les messages excédant 255 octets. L'utilisation de length_in_bytes comme paramètre d'entrée et de sortie permet le codage d'une boucle afin de traiter l'intégralité du texte du message. Le code suivant est un exemple de boucle et suppose que vous avez attribué à message_id un identificateur de message valide renvoyé par 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

Autorisations

Nécessite l'appartenance au rôle de serveur fixe sysadmin, mais les autorisations EXECUTE peuvent être accordées à d'autres utilisateurs. Cependant, pour des raisons de sécurité, nous vous conseillons de limiter les autorisations pour cette procédure stockée aux membres du rôle de serveur fixe sysadmin.

Exemples

L'exemple suivant renvoie l'état lors de la lecture d'un message. Dans cet exemple, la valeur d'un ID de message provenant de xp_findnextmsg est placée dans la variable locale @message_id et transmise à 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