xp_readmail (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 возвращает результирующий набор с этими столбцами.

Замечания

Все ошибки, кроме недопустимых параметров, заносятся в журнал приложений 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

См. также

Справочник