ヘッダーをスキップ
Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス
11g リリース1(11.1)
E05686-02
  目次
目次
索引
索引

戻る
戻る
 
次へ
次へ
 

216 UTL_SMTP

UTL_SMTPパッケージは、RFC821で定められたSimple Mail Transfer Protocol(SMTP)による電子メール送信ができるように設計されています。


関連項目:

SMTPパッケージを使用して電子メールを送信する方法については、『Oracle Databaseアドバンスト・アプリケーション開発者ガイド』を参照してください。

この章では、次の項目について説明します。


UTL_SMTPの使用方法


概要

プロトコルは、電子メール・クライアントからSMTPサーバーに電子メールを伝送するための一連のコマンドで構成されています。 UTL_SMTPパッケージでは、SMTPコマンドへのインタフェースを提供します。このパッケージには、多くのコマンドで利用できるプロシージャ形式およびファンクション形式のインタフェースが用意されています。ファンクション形式の場合、クライアントで処理するための応答はサーバーから戻されます。プロシージャ形式の場合は応答がチェックされ、一時的なエラー(400番台の応答コード)または永続的なエラー(500番台の応答コード)を示す応答のときには例外が発生します。そうでない場合は、応答を破棄します。

オリジナルのSMTPプロトコルによる通信には、7ビットASCIIが使用されることに注意してください。 UTL_SMTPを使用すると、すべてのテキスト・データ(つまり、VARCHAR2のデータ)は、サーバーに送信される前にUS7ASCIIに変換されます。 SMTP拡張8BITMIME [RFC1652]をサポートしているSMTPサーバーの実装の一部は、クライアントとサーバーの間の完全8ビット通信をサポートしています。DATAコマンドの本体は完全8ビットで転送できますが、それ以外のSMTPのコマンドと応答は7ビットです。 ターゲットのSMTPサーバーが8BITMIME拡張要素をサポートしている場合、マルチバイト・データベースのユーザーは、非US7ASCIIのマルチバイトVARCHAR2データをRAWに変換し、WRITE_RAW_DATAサブプログラムを使用して8ビットMIMEのエンコーディングを使用したマルチバイト・データを送信できます。

UTL_SMTPでは、RFC821に指定されているSMTP通信が提供されますが、メッセージの内容をRFC822に従って書式設定するためのAPI(電子メールの件名の設定など)は提供していません。メッセージの適切な書式設定は、ユーザー各自で行ってください。 また、UTL_SMTPは、SMTPを使用して電子メールを送信するように、SMTPサーバーをメール・クライアントに実装する機能は備えていません。


セキュリティ・モデル

このパッケージは実行者権限のパッケージになったため、起動するユーザーには、接続するリモート・ネットワーク・ホストに割り当てられたアクセス制御リストで接続権限が付与されている必要があります。


注意:

詳細は、『Oracle Databaseセキュリティ・ガイド』の外部ネットワーク・サービスへのファイングレイン・アクセスの管理に関する項を参照してください。


タイプ

connectionレコード・タイプ

SMTP接続を示すPL/SQLレコード・タイプです。

構文

TYPE connection IS RECORD (
    host              VARCHAR2(255),      -- remote host name
    port              PLS_INTEGER,        -- remote port number
    tx_timeout        PLS_INTEGER,        -- Transfer time out (in seconds)
    private_tcp_con   utl_tcp.connection, -- private, for implementation use
    private_state     PLS_INTEGER         -- private, for implementation use
);

フィールド

表216-1 connectionレコード・タイプのフィールド

フィールド 説明

host

接続が確立したときのリモート・ホストの名前。接続が確立されない場合はNULLです。

port

接続したリモートSMTPサーバーのポート番号。接続が確立されない場合はNULLです。

tx_timeout

この接続で読込みまたは書込み操作を中止するまでのUTL_SMTPパッケージの待機時間(秒)。読込み操作の場合、読み込めるデータがない場合に操作が即座に中止されます。書込み操作の場合、出力バッファがフルで、ブロックされずにネットワークに送信できるデータがない場合に操作が中止されます。0(ゼロ)は、まったく待機しないことを示します。NULLは、無期限に待機することを示します。

private_tcp_con

実装目的でのみ使用されるプライベートのパラメータ。このフィールドは変更しないでください。

private_state

実装目的でのみ使用されるプライベートのパラメータ。このフィールドは変更しないでください。


使用上の注意

接続レコードの読取り専用フィールドは、open_connectionを使用して接続に成功した後、SMTP接続の情報を戻すために使用されます。これらのフィールドを変更しても、接続には影響ありません。 private_xxxフィールドは、実装目的にのみ使用されます。これらのフィールドは変更しないでください。

reply、repliesレコード・タイプ

SMTP応答行を示すPL/SQLレコード・タイプです。各SMTP応答行は、応答コードとそれに続くテキスト・メッセージで構成されています。大半のSMTPコマンドに対しては単一の応答行ですが、一部のSMTPコマンドに対しては複数の応答行となります。このような場合は、複数の応答行を示すために応答レコードのPL/SQL表が使用されます。

構文

TYPE reply IS RECORD (
  code    PLS_INTEGER,       -- 3-digit reply code
  text    VARCHAR2(508)      -- text message
);
TYPE replies IS TABLE OF reply INDEX BY BINARY_INTEGER;   -- multiple reply lines

フィールド

表216-2 replyおよびrepliesレコード・タイプのフィールド

フィールド 説明

code

3桁の応答コード。

text

応答のテキスト・メッセージ。



応答コード

次のリストにSMTP応答コードを示します。

表216-3 SMTP応答コード

応答コード 意味

211

システム・ステータスまたはシステム・ヘルプの応答です。

214

ヘルプ・メッセージ(使用方法や特定の非標準コマンドの意味に関する情報で、この応答は人間であるユーザーにのみ有用です)。

220

<domain>サービスは準備完了です。

221

<domain>サービスは送信チャネルをクローズしています。

250

要求したメール・アクションは正常で、完了しました。

251

ユーザーがローカルではありません。<forward-path>にフォワードします。

252

OK。ノード<node>に対する保留中のメッセージが開始されました。ユーザーをVRFYできません(情報がローカルにないなど)が、このユーザーへのメッセージを送信しようとします。

253

OK。ノード<node>に対する保留中のメッセージ<messages>が開始されました。

354

メール入力を開始し、<CRLF>.<CRLF>で終了します。

355

オクテット・オフセットは、トランザクション・オフセットです。

421

<domain>サービスが使用不可のため、送信チャネルをクローズしています(サービスのシャットダウンが必要な場合には、すべてのコマンドに対してこの応答が使用される可能性があります)。

450

要求したメール・アクションが実行されていません。メールボックスは使用不可です(メールボックス・ビジーなど)。

451

要求したアクションが終了しました。処理中にローカル・エラーが発生しました。

452

要求したアクションが実行されていません。システム記憶域不足です。

453

電子メールがありません。

454

一時的にTLSを使用できません。要求した認証メカニズムには暗号化が必要です。

458

ノード<node>に対してメッセージをキューできません。

459

ノード<node>は許可されていません。理由:

500

構文エラーのため、コマンドを認識できません(コマンドラインが長すぎるなどのエラーも含まれます)。

501

パラメータまたは引数に構文エラーがあります。

502

コマンドが実装されていません。

503

コマンドの順序が不正です。

504

コマンド・パラメータが実装されていません。

521

<Machine>がメールを受け入れません。

530

STARTTLSコマンドを最初に発行する必要があります。要求した認証メカニズムには暗号化が必要です。

534

認証メカニズムが脆弱です。

538

要求した認証メカニズムには暗号化が必要です。

550

要求したアクションが実行されていません。メールボックスは使用不可です(メールボックスが見つからない、アクセスできないなど)。

551

ユーザーがローカルではありません。<forward-path>を試行してください。

552

要求したメール・アクションが終了しました。記憶域の割当て超過です。

553

要求したアクションが実行されていません。メールボックス名が使用不可です(メールボックスの構文が正しくないなど)。

554

トランザクションに失敗しました。



例外

次の表に、UTL_SMTPパッケージのインタフェースが呼び出す可能性のある例外を示します。ネットワーク・エラーは、応答コード421(サービスは使用不可)になります。

表216-4 UTL_SMTPの例外



INVALID_OPERATION

無効な操作が行われたときに呼び出されます。 つまり、open_dataをコールした後にwrite_datawrite_raw_dataまたはclose_data以外のAPIをコールした場合か、または初めにopen_dataをコールせずにwrite_datawrite_raw_dataまたはclose_dataをコールした場合です。

TRANSIENT_ERROR

400番台の応答コードを受け取った場合に呼び出されます。

PERMANENT_ERROR

500番台の応答コードを受け取った場合に呼び出されます。



ルールおよび制限

APIによる制限または範囲チェックはありません。ただし、SMTPの各種要素については、次のサイズ制限に注意する必要があります。制限を超えるデータが送信されると、サーバーからエラーが戻ります。

表216-5 SMTPのサイズ制限

要素 サイズ制限

user

ユーザー名の最大合計長は、64文字です。

domain

ドメイン名またはドメイン番号の最大合計長は、64文字です。

path

reverse-pathまたはforward-pathの最大合計長は256文字です(句読点と要素のセパレータも含む)。

command line

コマンド自体と<CRLF>も含めたコマンドラインの最大合計長は、512文字です。

reply line

応答コードと<CRLF>も含めた応答行の最大合計長は、512文字です。

text line

<CRLF>を含めたテキスト行の最大合計長は、1000文字です(ただし、透過性に必要な先行ドットはカウントされません)。

recipients buffer

バッファリングを要する受信者の最大合計数は、100です。



次の例では、アプリケーションでUTL_SMTPを使用して電子メールを送信する方法を示します。ポート25でSMTPサーバーに接続し、簡単なテキスト・メッセージを送信します。

DECLARE
  c UTL_SMTP.CONNECTION;

  PROCEDURE send_header(name IN VARCHAR2, header IN VARCHAR2) AS
  BEGIN
    UTL_SMTP.WRITE_DATA(c, name || ': ' || header || UTL_TCP.CRLF);
  END;

BEGIN
  c := UTL_SMTP.OPEN_CONNECTION('smtp-server.acme.com');
  UTL_SMTP.HELO(c, 'foo.com');
  UTL_SMTP.MAIL(c, 'sender@foo.com');
  UTL_SMTP.RCPT(c, 'recipient@foo.com');
  UTL_SMTP.OPEN_DATA(c);
  send_header('From',    '"Sender" <sender@foo.com>');
  send_header('To',      '"Recipient" <recipient@foo.com>');
  send_header('Subject', 'Hello');
  UTL_SMTP.WRITE_DATA(c, UTL_TCP.CRLF || 'Hello, world!');
  UTL_SMTP.CLOSE_DATA(c);
  UTL_SMTP.QUIT(c);
EXCEPTION
  WHEN utl_smtp.transient_error OR utl_smtp.permanent_error THEN
    BEGIN
      UTL_SMTP.QUIT(c);
    EXCEPTION
      WHEN UTL_SMTP.TRANSIENT_ERROR OR UTL_SMTP.PERMANENT_ERROR THEN
        NULL; -- When the SMTP server is down or unavailable, we don't have
              -- a connection to the server. The QUIT call will raise an
              -- exception that we can ignore.
    END;
    raise_application_error(-20000,
      'Failed to send mail due to the following error: ' || sqlerrm);
END;

UTL_SMTPサブプログラムの要約

表216-6 UTL_SMTPパッケージのサブプログラム

サブプログラム 説明

CLOSE_DATAファンクションおよびプロシージャ


データ・セッションをクローズします。

COMMANDファンクションおよびプロシージャ


一般的なSMTPコマンドを実行します。

COMMAND_REPLIESファンクション


接続後にSMTPサーバーとの初期ハンドシェイクを実行します。

DATAファンクションおよびプロシージャ


接続後、戻された詳細な情報を使用してSMTPサーバーとの初期ハンドシェイクを実行します。

EHLOファンクションおよびプロシージャ


接続後、戻された詳細な情報を使用してSMTPサーバーとの初期ハンドシェイクを実行します。

HELOファンクションおよびプロシージャ


接続後にSMTPサーバーとの初期ハンドシェイクを実行します。

HELPファンクション


HELPコマンドを送信します。

MAILファンクションおよびプロシージャ


サーバーとのメール・トランザクションを開始します。宛先はメールボックスです。

NOOPファンクションおよびプロシージャ


NULLのコマンドです。

OPEN_CONNECTIONファンクション


SMTPサーバーへの接続をオープンします。

OPEN_DATAファンクションおよびプロシージャ


DATAコマンドを送信します。

QUITファンクションおよびプロシージャ


SMTPセッションを終了し、サーバーとの接続を切断します。

RCPTファンクション


電子メール・メッセージの受信者を指定します。

RSETファンクションおよびプロシージャ


現行のメール・トランザクションを終了します。

VRFYファンクション


宛先の電子メール・アドレスの妥当性を検証します。

WRITE_DATAプロシージャ


電子メール・メッセージの一部を書き込みます。

WRITE_RAW_DATAプロシージャ


RAWデータを使用して電子メール・メッセージの一部を書き込みます。



CLOSE_DATAファンクションおよびプロシージャ

CLOSE_DATAコールは、<CR><LF>.<CR><LF>(行の開始はシングル・ピリオド)の順序で送信することにより、電子メール・メッセージを終了します。

構文

UTL_SMTP.CLOSE_DATA (
   c     IN OUT NOCOPY connection)
RETURN reply;

UTL_SMTP.CLOSE_DATA (
   c     IN OUT NOCOPY connection);

パラメータ

表216-7 CLOSE_DATAファンクションおよびプロシージャのパラメータ

パラメータ 説明

c

SMTP接続。


戻り値

表216-8 CLOSE_DATAファンクションおよびプロシージャの戻り値

戻り値 説明

reply

コマンドの応答(「reply、repliesレコード・タイプ」を参照)。複数の応答が存在する場合は、最後の応答が戻されます。


使用上の注意

OPEN_DATAWRITE_DATAWRITE_RAW_DATAおよびCLOSE_DATAへのコールは、正しい順序で実行する必要があります。最初に、SMTPサーバーにDATAコマンドを送信するために、OPEN_DATAをコールすると、次に、実際のデータを送信するために、WRITE_DATAまたはWRITE_RAW_DATAを繰り返しコールできます。データは、CLOSE_DATAをコールして終了します。OPEN_DATAがコールされた後にコールできるサブプログラムは、WRITE_DATAWRITE_RAW_DATA,またはCLOSE_DATAのみです。他のAPIへのコールは、INVALID_OPERATION例外の発生原因となります。

CLOSE_DATAは、必ずOPEN_CONNECTIONHELOまたはEHLOMAILおよびRCPTがコールされた後にコールしてください。このルーチンがコールされるときは、SMTPサーバーへの接続がオープン状態で、メール・トランザクションがアクティブ状態である必要があります。

SMTPサーバーからの応答は、CLOSE_DATAへのコール中にデータの終了が送信されるまで行われないため、WRITE_DATAのファンクション形式は存在しないことに注意してください。


COMMANDファンクションおよびプロシージャ

このファンクションおよびプロシージャは、一般的なSMTPコマンドを実行します。

構文

UTL_SMTP.COMMAND (
   c     IN OUT NOCOPY    connection,
   cmd   IN               VARCHAR2,
   arg   IN               VARCHAR2 DEFAULT NULL)
RETURN reply;

UTL_SMTP.COMMAND (
   c     IN OUT NOCOPY    connection,
   cmd   IN               VARCHAR2,
   arg   IN               VARCHAR2 DEFAULT NULL);

パラメータ

表216-9 COMMANDファンクションおよびプロシージャのパラメータ

パラメータ 説明

c

SMTP接続。

cmd

サーバーに送信するSMTPコマンド。

arg

SMTP引数へのオプション引数。cmdargの間に空白が挿入されます。


戻り値

表216-10 COMMANDファンクションおよびプロシージャの戻り値

戻り値 説明

reply

コマンドの応答(「reply、repliesレコード・タイプ」を参照)。複数の応答が存在する場合は、最後の応答が戻されます。


使用上の注意

このファンクションは、一般的なSMTPコマンドを起動するために使用されます。COMMANDは、単一の応答行が予想される場合にのみ使用します。複数の応答行が予想される場合は、COMMAND_REPLIESを使用します。

COMMANDは、SMTPサーバーからの応答が複数行ある場合、最終応答行のみを戻します。


COMMAND_REPLIESファンクション

このファンクションは、一般的なSMTPコマンドを実行します。

構文

UTL_SMTP.COMMAND_REPLIES (
   c     IN OUT NOCOPY    connection,
   cmd   IN               VARCHAR2,
   arg   IN               VARCHAR2 DEFAULT NULL)
RETURN replies;

パラメータ

表216-11 COMMAND_REPLIESファンクションのパラメータ

パラメータ 説明

c

SMTP接続。

cmd

サーバーに送信するSMTPコマンド。

arg

SMTP引数へのオプション引数。cmdargの間に空白が挿入されます。


戻り値

表216-12 COMMAND_REPLIESファンクションの戻り値

戻り値 説明

replies

コマンドの応答(「reply、repliesレコード・タイプ」を参照)。


使用上の注意

このファンクションは、一般的なSMTPコマンドを起動するために使用されます。COMMANDは、単一の応答行が予想される場合にのみ使用します。複数の応答行が予想される場合は、COMMAND_REPLIESを使用します。

COMMANDは、SMTPサーバーからの応答が複数行ある場合、最終応答行のみを戻します。


DATAファンクションおよびプロシージャ

このファンクションおよびプロシージャは、電子メール・メッセージの本文を指定します。

構文

UTL_SMTP.DATA (
   c     IN OUT NOCOPY connection
   body  IN  VARCHAR2 CHARACTER SET ANY_CS)
RETURN reply;

UTL_SMTP.DATA (
   c     IN OUT NOCOPY connection
   body  IN VARCHAR2 CHARACTER SET ANY_CS);

パラメータ

表216-13 DATAファンクションおよびプロシージャのパラメータ

パラメータ 説明

c

SMTP接続。

body

送信するメッセージのヘッダーを含めたテキスト([RFC822]形式)。


戻り値

表216-14 DATAファンクションおよびプロシージャの戻り値

戻り値 説明

reply

コマンドの応答(「reply、repliesレコード・タイプ」を参照)。複数の応答が存在する場合は、最後の応答が戻されます。


使用上の注意

bodyパラメータの内容がMIME(RFC822)の仕様に準拠していることをアプリケーションにより確認する必要があります。DATAルーチンは、RFC821の要求に従って、<CR><LF>.<CR><LF>の順序で(行の開始はシングル・ピリオド)メッセージを終了します。 また、bodyの<CR><LF>.<CR><LF>(シングル・ピリオド)の順序を<CR><LF>..<CR><LF>(ダブル・ピリオド)に変換します。この変換によって、RFC821のセクション4.5.2に記述されている透過性が提供されます。

DATAは、必ずOPEN_CONNECTIONHELOまたはEHLOMAILおよびRCPTがコールされた後にコールしてください。このルーチンがコールされるときは、SMTPサーバーへの接続がオープン状態で、メール・トランザクションがアクティブ状態である必要があります。

サーバーからの応答は、ステータス・コード250で開始するメッセージになります。初期DATAコマンドから受信した354という応答は、コール元に戻されません。


EHLOファンクションおよびプロシージャ

このファンクションおよびプロシージャは、接続後、戻された詳細な情報を使用してSMTPサーバーとの初期ハンドシェイクを実行します。

構文

UTL_SMTP.EHLO (
   c       IN OUT NOCOPY connection,
   domain  IN)
RETURN replies;

UTL_SMTP.EHLO (
   c       IN OUT NOCOPY connection,
   domain  IN);

パラメータ

表216-15 EHLOファンクションおよびプロシージャのパラメータ

パラメータ 説明

c

SMTP接続。

domain

ローカル(送信側)ホストのドメイン名。識別の目的で使用されます。


戻り値

表216-16 EHLOファンクションおよびプロシージャの戻り値

戻り値 説明

replies

コマンドの応答(「reply、repliesレコード・タイプ」を参照)。


使用上の注意

EHLOのインタフェースは、サーバーがその構成に関するより多くの詳細な情報を戻せることを除くとHELOと同じです。 [RFC1869]には、戻される情報の書式が指定されています。書式は、PL/SQLアプリケーションでこのコールのファンクション形式を使用して取り出すことができます。HELOとの互換性のために、サーバーが戻すテキストの各行はステータス・コード250で開始されます。

関連ファンクション

HELO


HELOファンクションおよびプロシージャ

このファンクションおよびプロシージャは、接続後にSMTPサーバーとの初期ハンドシェイクを実行します。

構文

UTL_SMTP.HELO (
   c       IN OUT NOCOPY   connection,
   domain  IN              VARCHAR2)
RETURN reply;

UTL_SMTP.HELO (
   c       IN OUT NOCOPY   connection,
   domain  IN              VARCHAR2);

パラメータ

表216-17 HELOファンクションおよびプロシージャのパラメータ

パラメータ 説明

c

SMTP接続。

domain

ローカル(送信側)ホストのドメイン名。識別の目的で使用されます。


戻り値

表216-18 HELOファンクションおよびプロシージャの戻り値

戻り値 説明

reply

コマンドの応答(「reply、repliesレコード・タイプ」を参照)。複数の応答が存在する場合は、最後の応答が戻されます。


使用上の注意

RFC821では、接続した後でクライアントはサーバーに対してクライアント自体を識別する必要があると指定されています。このルーチンは、その識別を実行します。 このルーチンをコールする前に、OPEN_CONNECTIONファンクションをコールして接続をオープンにしておく必要があります。

サーバーからの応答は、ステータス・コード250で開始するメッセージになります。

関連ファンクション

EHLO


HELPファンクション

このファンクションは、HELPコマンドを送信します。

構文

UTL_SMTP.HELP (
   c         IN OUT NOCOPY   connection,
   command   IN              VARCHAR2 DEFAULT NULL)
RETURN replies;

パラメータ

表216-19 HELPファンクションのパラメータ

パラメータ 説明

c

SMTP接続。

command

ヘルプ・メッセージを取得するコマンド。


戻り値

表216-20 HELPファンクションの戻り値

戻り値 説明

replies

コマンドの応答(「reply、repliesレコード・タイプ」を参照)。



MAILファンクションおよびプロシージャ

このファンクションおよびプロシージャは、サーバーとのメール・トランザクションを開始します。宛先はメールボックスです。

構文

UTL_SMTP.MAIL (
   c           IN OUT NOCOPY   connection,
   sender      IN              VARCHAR2,
   parameters  IN              VARCHAR2 DEFAULT NULL)
RETURN reply;

UTL_SMTP.MAIL (
   c           IN OUT NOCOPY   connection,
   sender      IN              VARCHAR2,
   parameters  IN              VARCHAR2 DEFAULT NULL);

パラメータ

表216-21 MAILファンクションおよびプロシージャのパラメータ

パラメータ 説明

c

SMTP接続。

sender

メッセージを送信するユーザーの電子メール・アドレス。

parameters

[RFC1869]のセクション6に定義されているMAILコマンドへの追加パラメータ。XXX=XXX (XXX=XXX ....)の形式に従ってください。


戻り値

表216-22 MAILファンクションおよびプロシージャの戻り値

戻り値 説明

reply

コマンドの応答(「reply、repliesレコード・タイプ」を参照)。複数の応答が存在する場合は、最後の応答が戻されます。


使用上の注意

このコマンドはメッセージを送信しません。準備を開始するのみです。トランザクションを完了するには、このコマンドの後にRCPTDATAへのコールが必要です。SMTPサーバーへの接続はオープン状態で、HELOまたはEHLOコマンドはすでに送信されている必要があります。

サーバーからの応答は、ステータス・コード250で開始するメッセージになります。


NOOPファンクションおよびプロシージャ

NULLのコマンドです。

構文

UTL_SMTP.NOOP (
   c  IN OUT NOCOPY connection)
RETURN reply;

UTL_SMTP.NOOP (
   c  IN OUT NOCOPY connection);

パラメータ

表216-23 NOOPファンクションおよびプロシージャのパラメータ

パラメータ 説明

c

SMTP接続。


戻り値

表216-24 NOOPファンクションおよびプロシージャの戻り値

戻り値 説明

reply

コマンドの応答(「reply、repliesレコード・タイプ」を参照)。複数の応答が存在する場合は、最後の応答が戻されます。


使用上の注意

このコマンドは、サーバーから正常な応答を引き出すことにのみ有効です。 OPEN_CONNECTIONでサーバーへの接続を確立した後は、いつでもこのコマンドを発行できます。NOOPコマンドは、サーバーが接続され、正しくリスニングが行われていることを検証するために使用します。

このコマンドの応答は、常にステータス・コード250で開始する単一の行になります。


OPEN_CONNECTIONファンクション

このファンクションは、SMTPサーバーへの接続をオープンします。

構文

UTL_SMTP.OPEN_CONNECTION (
   host        IN  VARCHAR2,
   port        IN  PLS_INTEGER DEFAULT 25,
   c           OUT connection,
   tx_timeout  IN  PLS_INTEGER DEFAULT NULL)
RETURN reply;

UTL_SMTP.OPEN_CONNECTION (
   host        IN  VARCHAR2,
   port        IN  PLS_INTEGER DEFAULT 25,
   tx_timeout  IN  PLS_INTEGER DEFAULT NULL)
RETURN connection;

パラメータ

表216-25 OPEN_CONNECTIONファンクションのパラメータ

パラメータ 説明

host

SMTPサーバーのホストの名前。

port

SMTPサーバーがリスニングするポート番号(通常は25)。

c

SMTP接続。

tx_timeout

この接続で読込みまたは書込み操作を中止するまでのUTL_SMTPパッケージの待機時間(秒)。読込み操作の場合、読み込めるデータがない場合に操作が即座に中止されます。書込み操作の場合、出力バッファがフルで、ブロックされずにネットワークに送信できるデータがない場合に操作が中止されます。0(ゼロ)は、まったく待機しないことを示します。NULLは、無期限に待機することを示します。


戻り値

表216-26 OPEN_CONNECTIONファンクションの戻り値

戻り値 説明

reply

コマンドの応答(「reply、repliesレコード・タイプ」を参照)。複数の応答が存在する場合は、最後の応答が戻されます。


使用上の注意


OPEN_DATAファンクションおよびプロシージャ

OPEN_DATADATAコマンドを送信し、その後、WRITE_DATAおよびWRITE_RAW_DATAで電子メール・メッセージの一部を書き込みます。

構文

UTL_SMTP.OPEN_DATA (
   c     IN OUT NOCOPY connection)
RETURN reply;

UTL_SMTP.OPEN_DATA (
   c     IN OUT NOCOPY connection);

パラメータ

表216-27 OPEN_DATAファンクションおよびプロシージャのパラメータ

パラメータ 説明

c

SMTP接続。

data

送信するメッセージのヘッダーを含めたテキストの一部([RFC822]形式)。


戻り値

表216-28 OPEN_DATAファンクションおよびプロシージャの戻り値

戻り値 説明

reply

コマンドの応答(「reply、repliesレコード・タイプ」を参照)。複数の応答が存在する場合は、最後の応答が戻されます。


使用上の注意

OPEN_DATAWRITE_DATAWRITE_RAW_DATAおよびCLOSE_DATAへのコールは、正しい順序で実行する必要があります。最初に、SMTPサーバーにDATAコマンドを送信するために、OPEN_DATAをコールすると、次に、実際のデータを送信するために、WRITE_DATAまたはWRITE_RAW_DATAを繰り返しコールできます。データは、CLOSE_DATAをコールして終了します。OPEN_DATAがコールされた後にコールできるサブプログラムは、WRITE_DATAWRITE_RAW_DATA,またはCLOSE_DATAのみです。他のAPIへのコールは、INVALID_OPERATION例外の発生原因となります。

OPEN_DATAは、必ずOPEN_CONNECTIONHELOまたはEHLOMAILおよびRCPTがコールされた後にコールしてください。このルーチンがコールされるときは、SMTPサーバーへの接続がオープン状態で、メール・トランザクションがアクティブ状態である必要があります。


QUITファンクションおよびプロシージャ

このファンクションは、SMTPセッションを終了し、サーバーとの接続を切断します。

構文

UTL_SMTP.QUIT (
   c  IN OUT NOCOPY connection)
RETURN reply;

UTL_SMTP.QUIT (
   c  IN OUT NOCOPY connection);

パラメータ

表216-29 QUITファンクションおよびプロシージャのパラメータ

パラメータ 説明

c

SMTP接続。


戻り値

表216-30 QUITファンクションおよびプロシージャの戻り値

戻り値 説明

reply

コマンドの応答(「reply、repliesレコード・タイプ」を参照)。複数の応答が存在する場合は、最後の応答が戻されます。


使用上の注意

QUITコマンドは、セッションを終了するというクライアントの意図をSMTPサーバーに伝えます。 伝えた後に、OPEN_CONNECTIONで確立した接続をクローズします。このOPEN_CONNECTIONは、このコマンドの実行前にコールされている必要があります。QUITの発行時にメール・トランザクションが進行中の場合は、RSETと同様に放棄されます。

このコマンドのファンクション形式は、正常終了時にステータス・コード221で開始する単一の行を戻します。SMTPサーバーへの接続は、どのような場合にもクローズされます。 cREMOTE_HOSTおよびREMOTE_PORTフィールドはリセットされます。

関連ファンクション

RSET


RCPTファンクション

このファンクションおよびプロシージャは、電子メール・メッセージの受信者を指定します。

構文

UTL_SMTP.RCPT (
   c           IN OUT NOCOPY     connection,
   recipient   IN                VARCHAR2,
   parameters  IN                VARCHAR2 DEFAULT NULL)
RETURN reply;

UTL_SMTP.RCPT (
   c           IN OUT NOCOPY     connection,
   recipient   IN                VARCHAR2,
   parameters  IN                VARCHAR2 DEFAULT NULL);

表216-31 RCPTファンクションおよびプロシージャのパラメータ

パラメータ 説明

c

SMTP接続。

recipient

メッセージの送信先ユーザーの電子メール・アドレス。

parameters

[RFC1869]のセクション6に定義されているRCPTコマンドへの追加パラメータ。XXX=XXX (XXX=XXX ....)の形式に従ってください。


戻り値

表216-32 RCPTファンクションおよびプロシージャの戻り値

戻り値 説明

reply

コマンドの応答(「reply、repliesレコード・タイプ」を参照)。複数の応答が存在する場合は、最後の応答が戻されます。


使用上の注意

複数の受信者にメッセージを送信するには、このルーチンを複数回コールします。各起動で1つの電子メール・アドレスへの配信がスケジュールされます。 メッセージ・トランザクションは、先行するMAILへのコールによって開始されており、メール・サーバーへの接続はすでにオープン状態にあり、先行するOPEN_CONNECTIONおよびHELOまたはEHLOへのコールによってそれぞれ初期化されている必要があります。

サーバーからの応答は、ステータス・コード250または251で開始するメッセージになります。


RSETファンクションおよびプロシージャ

このファンクションは、現行のメール・トランザクションを終了します。

構文

UTL_SMTP.RSET (
   c  IN OUT NOCOPY connection)
RETURN reply;

UTL_SMTP.RSET (
   c  IN OUT NOCOPY connection);

パラメータ

表216-33 RSETファンクションおよびプロシージャのパラメータ

パラメータ 説明

c

SMTP接続。


戻り値

表216-34 RSETファンクションおよびプロシージャの戻り値

戻り値 説明

reply

コマンドの応答(「reply、repliesレコード・タイプ」を参照)。複数の応答が存在する場合は、最後の応答が戻されます。


使用上の注意

このコマンドによって、クライアントは構成処理中のメール・メッセージを放棄できます。メールは送信されません。 クライアントは、SMTPサーバーへの接続がOPEN_CONNECTIONでオープンされた後は、DATAまたはOPEN_DATAがコールされるまで、いつでもRSETをコールできます。ただし、電子メール・データの送信が始まってしまった後では、その送信を中止できません。

サーバーは、RSETに対してステータス・コード250で開始するメッセージで常に応答します。

関連ファンクション

QUIT


VRFYファンクション

このファンクションは、宛先の電子メール・アドレスの妥当性を検証します。

構文

UTL_SMTP.VRFY (
   c          IN OUT NOCOPY connection
   recipient  IN VARCHAR2)
RETURN reply;

パラメータ

表216-35 VRFYファンクションのパラメータ

パラメータ 説明

c

SMTP接続。

recipient

検証される電子メール・アドレス。


戻り値

表216-36 VRFYファンクションの戻り値

戻り値 説明

reply

コマンドの応答(「reply、repliesレコード・タイプ」を参照)。複数の応答が存在する場合は、最後の応答が戻されます。


使用上の注意

サーバーは、宛先アドレスrecipientの解決を試みます。解決した場合、サーバーは受信者のフルネームと完全修飾メールボックス・パスを戻します。 この要求の実行前には、OPEN_CONNECTION、およびHELOまたはEHLOを介して、サーバーへの接続が確立されている必要があります。

検証が正常に終了した場合は、ステータス・コード250または251で開始する1行以上の行が戻されます。


WRITE_DATAプロシージャ

WRITE_DATAを使用して、電子メール・メッセージの一部を書き込みます。 WRITE_DATAを繰り返しコールして、電子メール・メッセージにデータを追加します。

構文

UTL_SMTP.WRITE_DATA (
   c     IN OUT NOCOPY connection,
   data  IN VARCHAR2 CHARACTER SET ANY_CS);

パラメータ

表216-37 WRITE_DATAプロシージャのパラメータ

パラメータ 説明

c

SMTP接続。

data

送信するメッセージのヘッダーを含めたテキストの一部([RFC822]形式)。


使用上の注意

OPEN_DATAWRITE_DATAWRITE_RAW_DATAおよびCLOSE_DATAへのコールは、正しい順序で実行する必要があります。最初に、SMTPサーバーにDATAコマンドを送信するために、OPEN_DATAをコールすると、次に、実際のデータを送信するために、WRITE_DATAまたはWRITE_RAW_DATAを繰り返しコールできます。データは、CLOSE_DATAをコールして終了します。OPEN_DATAがコールされた後にコールできるサブプログラムは、WRITE_DATAWRITE_RAW_DATA,またはCLOSE_DATAのみです。他のAPIへのコールは、INVALID_OPERATION例外の発生原因となります。

bodyパラメータの内容がMIME(RFC822)の仕様に準拠していることをアプリケーションにより確認する必要があります。DATAルーチンは、RFC821の要求に従って、<CR><LF>.<CR><LF>の順序で(行の開始はシングル・ピリオド)メッセージを終了します。また、bodyの<CR><LF>.<CR><LF>(シングル・ピリオド)の順序を<CR><LF>..<CR><LF>(ダブル・ピリオド)に変換します。この変換によって、RFC821のセクション4.5.2に記述されている透過性が提供されます。

この変換は完全でないことに注意してください。このコード・フラグメントを次に示します。

  UTL_SMTP.WRITE_DATA('some message.' || chr(13) || chr(10));
  UTL_SMTP.WRITE_DATA('.' || chr(13) || chr(10));

順序<CR><LF>.<CR><LF>は、WRITE_DATAへの2回のコールに分割されるため、WRITE_DATAの実装によって、データの終了順序は検出されません。したがって、変換も実行されません。このような状態は、ユーザーの責任で処理する必要があります。処理が行われない場合、メッセージ・データの終端が不完全となる可能性があります。

WRITE_DATAは、必ずOPEN_CONNECTIONHELOまたはEHLOMAILおよびRCPTがコールされた後にコールしてください。このルーチンがコールされるときは、SMTPサーバーへの接続がオープン状態で、メール・トランザクションがアクティブ状態である必要があります。

SMTPサーバーからの応答は、CLOSE_DATAへのコール中にデータの終了が送信されるまで行われないため、WRITE_DATAのファンクション形式は存在しないことに注意してください。

WRITE_DATAを使用して送信するテキスト(VARCHAR2)データは、送信前にUS7ASCIIに変換されます。テキストにマルチバイト・キャラクタが含まれている場合は、テキスト内のUS7ASCIIに変換できない各マルチバイト・キャラクタが'?'文字に置き換えられます。EHLOサブプログラムを使用してSMTPサーバーとの間で8BITMIME拡張要素を処理する場合は、最初にUTL_RAWパッケージでテキストをRAWに変換してから、WRITE_RAW_DATAを使用してRAWデータを送信することによって、マルチバイトのVARCHAR2データを送信できます。


WRITE_RAW_DATAプロシージャ

WRITE_RAW_DATAを使用して、電子メール・メッセージの一部を書き込みます。 WRITE_RAW_DATAを繰り返しコールして、電子メール・メッセージにデータを追加します。

構文

UTL_SMTP.WRITE_RAW_DATA (
   c     IN OUT NOCOPY connection
   data  IN RAW);

パラメータ

表216-38 WRITE_RAW_DATAプロシージャのパラメータ

パラメータ 説明

c

SMTP接続。

data

送信するメッセージのヘッダーを含めたテキストの一部([RFC822]形式)。


使用上の注意

OPEN_DATAWRITE_DATAWRITE_RAW_DATAおよびCLOSE_DATAへのコールは、正しい順序で実行する必要があります。最初に、SMTPサーバーにDATAコマンドを送信するために、OPEN_DATAをコールすると、次に、実際のデータを送信するために、WRITE_DATAまたはWRITE_RAW_DATAを繰り返しコールできます。データは、CLOSE_DATAをコールして終了します。OPEN_DATAがコールされた後にコールできるサブプログラムは、WRITE_DATAWRITE_RAW_DATA,またはCLOSE_DATAのみです。他のAPIへのコールは、INVALID_OPERATION例外の発生原因となります。

bodyパラメータの内容がMIME(RFC822)の仕様に準拠していることをアプリケーションにより確認する必要があります。DATAルーチンは、RFC821の要求に従って、<CR><LF>.<CR><LF>の順序で(行の開始はシングル・ピリオド)メッセージを終了します。また、bodyの<CR><LF>.<CR><LF>(シングル・ピリオド)の順序を<CR><LF>..<CR><LF>(ダブル・ピリオド)に変換します。この変換によって、RFC821のセクション4.5.2に記述されている透過性が提供されます。

この変換は完全でないことに注意してください。このコード・フラグメントを次に示します。

  UTL_SMTP.WRITE_DATA('some message.' || chr(13) || chr(10));
  UTL_SMTP.WRITE_DATA('.' || chr(13) || chr(10));

順序<CR><LF>.<CR><LF>は、WRITE_DATAへの2回のコールに分割されるため、WRITE_DATAの実装によって、データの終了順序は検出されません。したがって、変換も実行されません。このような状態は、ユーザーの責任で処理する必要があります。処理が行われない場合、メッセージ・データの終端が不完全となる可能性があります。

XXX_DATAは、必ずOPEN_CONNECTIONHELOまたはEHLOMAILおよびRCPTがコールされた後にコールしてください。このルーチンがコールされるときは、SMTPサーバーへの接続がオープン状態で、メール・トランザクションがアクティブ状態である必要があります。

SMTPサーバーからの応答は、CLOSE_DATAへのコール中にデータの終了が送信されるまで行われないため、WRITE_DATAのファンクション形式は存在しないことに注意してください。

WRITE_DATAを使用して送信するテキスト(VARCHAR2)データは、送信前にUS7ASCIIに変換されます。テキストにマルチバイト・キャラクタが含まれている場合は、テキスト内のUS7ASCIIに変換できない各マルチバイト・キャラクタが'?'文字に置き換えられます。EHLOサブプログラムを使用してSMTPサーバーとの間で8BITMIME拡張要素を処理する場合は、最初にUTL_RAWパッケージでテキストをRAWに変換してから、WRITE_RAW_DATAを使用してRAWデータを送信することによって、マルチバイトのVARCHAR2データを送信できます。