xp_readmail (Transact-SQL)

Считывает электронное сообщение из входящего почтового ящика службы SQL Mail. Эта процедура используется процедурой sp_processmail для обработки всех почтовых сообщений, находящихся во входящего ящике службы SQL Mail.

Примечание
В будущей версии Microsoft SQL Server эта возможность будет удалена. Избегайте использования этой возможности в новых разработках и запланируйте изменение существующих приложений, в которых она применяется.

Синтаксические обозначения в Transact-SQL

Синтаксис

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

  Если используется на входе, он должен определять тип определенного сообщения; аргумент type на входе не обрабатывается, если message_id равен NULL. Аргумент 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) и не имеет значения по умолчанию. Если почтовый сервер не предоставляет значения поля «Скрытая копия», аргумент 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 не удаляет эти вложения, поэтому каждое вложение должно удаляться вручную.

Чтобы считать одно сообщение из входного ящика, укажите допустимый идентификатор message_id, возвращаемый процедурой xp_findnextmsg в качестве входного параметра для процедуры xp_readmail. Можно указать аргументы peek и suppress_attach в качестве входных параметров для управления способом чтения сообщения. При использовании в этом методе параметров peek и suppress_attach все другие параметры являются необязательными выходными параметрами, содержащими специальные сведения из считываемого сообщения.

Использование процедуры xp_findnextmsg в качестве входного параметра для процедуры xp_readmail рассмотрим на примере выполнения следующей команды:

sp_helptext 'sp_processmail';

При использовании для считывания одного сообщения xp_readmail может считывать текст сообщения секциями длиной более 255 байт. Для считывания текста сообщения секциями длиной больше 255 байт используйте аргумент length_in_bytes. Использование 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

См. также

Справочник

sp_processmail (Transact-SQL)

Системные хранимые процедуры (Transact-SQL)

xp_deletemail (Transact-SQL)

xp_findnextmsg (Transact-SQL)

xp_sendmail (Transact-SQL)

xp_startmail (Transact-SQL)

xp_stopmail (Transact-SQL)