Release 2 (8.1.6)
Part Number A76936-01
 Library |
 Product |
 Contents |
 Index |
| Oracle8i Supplied PL/SQL Packages Reference Release 2 (8.1.6) Part Number A76936-01 |
|
UTL_SMTP , 2 of 6
A PL/SQL record type to represent a SMTP connection.
TYPE connection IS RECORD ( host VARCHAR2(255), -- remote host name port PLS_INTEGER, -- remote port number private_tcp_con utl_tcp.connection, -- private, for implementation use private_state PLS_INTEGER -- private, for implementation use );
The name of the remote host when connection is established. NULL when no connection is established.
The port number of the remote SMTP server connected. NULL when no connection is established.
Private, for implementation use only. Users should not modify this field.
The field "private_tcp_con" is for implementation use only.
A PL/SQL record type to represent a SMTP reply line. Each SMTP reply line consists of a reply code followed by a text message. While a single reply line is expected for most SMTP commands, some SMTP commands expect multiple reply lines. For those situations, a PL/SQL table of reply records is used to represent multiple reply lines.
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
The 3-digit reply code.
The text message of the reply.
Open a connection to an SMTP server.
FUNCTION open_connection (host IN VARCHAR2,
port IN PLS_INTEGER DEFAULT 25,
c OUT NOCOPY connection ) RETURN reply;
FUNCTION open_connection (host IN VARCHAR2,
port IN PLS_INTEGER DEFAULT 25
) return connection;
Name of SMTP server host
port (IN)Port number on which SMTP server is listening (usually 25)
The expected response from the server is a message beginning with status code 220.
The version of open_connection()API that returns utl_smtp.connection record is actually the procedure version of open_connection that checks the reply code returned by a SMTP server when connection is first established.
Perform a generic SMTP command.
FUNCTION command(c IN connection, cmd IN VARCHAR2, arg IN VARCHAR2 DEFAULT NULL) RETURN reply; PROCEDURE command(c IN connection, cmd IN VARCHAR2, arg IN VARCHAR2 DEFAULT NULL); FUNCTION command_replies(c IN connection, cmd IN VARCHAR2, arg IN VARCHAR2 DEFAULT NULL) RETURN replies;
The SMTP connection.
The SMTP command to send to the server.
The optional argument to the SMTP argument. A space will be inserted between p_command and p_argument.
These are the APIs to invoke a generic SMTP command. Use command() if only a single reply line is expected. Use command_replies() if multiple reply lines are expected (in other words, EXPN or HELP).
For command(), if multiple reply lines are returned from the SMTP server, it returns the last reply line only.
Perform initial handshaking with SMTP server after connecting.
FUNCTION helo (c IN OUT NOCOPY connection, domain IN VARCHAR2 DEFAULT NULL) RETURN reply; PROCEDURE helo (c IN OUT NOCOPY connection, domain IN VARCHAR2 DEFAULT NULL);
The SMTP connection.
RFC 821 specifies that the client must identify itself to the server after connecting. This routine performs that identification. The connection must have been opened via a call to open_connection() before calling this routine.
The expected response from the server is a message beginning with status code 250.
ehlo()
Perform initial handshaking with SMTP server after connecting, with extended information returned.
FUNCTION ehlo (c IN OUT NOCOPY connection, domain IN VARCHAR2 DEFAULT NULL) RETURN replies; PROCEDURE ehlo (c IN OUT NOCOPY connection, domain IN VARCHAR2 DEFAULT NULL);
The SMTP connection.
Domain name of the local (sending) host. Used for identification purposes.
The ehlo() interface is identical to helo(), except that it allows the server to return more descriptive information about its configuration. [RFC1869] specifies the format of the information returned, which the PL/SQL application can retrieve using the functional form of this call. For compatibility with helo(), each line of text returned by the server begins with status code 250.
helo()
Initiate a mail transaction with the server. The destination is a mailbox.
The SMTP connection.
The email address of the user sending the message.
The additional parameters to MAIL command as defined in Section 6 of [RFC1869]. It should follow the format of "XXX=XXX (XXX=XXX ....)".
This command does not send the message, it simply begins its preparation. It must be followed by calls to rcpt() and data() to complete the transaction. The connection to the SMTP server must be open and a helo() or ehlo() command must have already been sent.
The expected response from the server is a message beginning with status code 250.
Specify the recipient of an email message.
FUNCTION rcpt (c IN OUT NOCOPY connection, recipient IN VARCHAR2, parameters IN OUT NOCOPY VARCHAR2 DEFAULT NULL) RETURN reply; PROCEDURE rcpt (c IN OUT NOCOPY connection, recipient IN VARCHAR2, parameters IN VARCHAR2 DEFAULT NULL);
The SMTP connection.
The email address of the user to which the message is being sent.
The additional parameters to RCPT command as defined in Section 6 of [RFC1869]. It should follow the format of "XXX=XXX (XXX=XXX ....)".
To send a message to multiple recipients, call this routine multiple times. Each invocation schedules delivery to a single email address. The message transaction must have been begin by a prior call to mail(), and the connection to the mail server must have been opened and initialized by prior calls to open_connection() and helo() or ehlo(), respectively.
The expected response from the server is a message beginning with status code 250 or 251.
Specify the body of an email message.
FUNCTION data (c IN OUT NOCOPY connection, body IN VARCHAR2) RETURN reply; PROCEDURE data (c IN OUT NOCOPY connection, body IN VARCHAR2);
The SMTP connection.
The text of the message to be sent, including headers, in [RFC822] format.
It is the application's responsibility to ensure that contents of the message parameter conform to the [RFC822] specification. The data() routine will terminate the message with a "<CR><LF>.<CR><LF>" sequence (a single period at the beginning of a line), as required by [RFC821]. It will also translate any sequences of "<CR><LF>.<CR><LF>" (single period) in message to "<CR><LF>..<CR><LF>" (double period). This conversion provides the transparency as described in Section 4.5.2 of [RFC821].
data() should only be called after open_connection(), helo() / ehlo(), mail() and rcpt() have been called. The connection to the SMTP server must be open and a mail transaction active when this routine is called.
The expected response from the server is a message beginning with status code 250. The 354 response received from the initial DATA command will not be returned to the caller.
These 3 APIs provided a more fine-grain control to the data()API, in other words, to the SMTP DATA operation. open_data() sends the DATA command. After that, write_data() writes a portion of the email message. Repeat call to write_data() appends data to the email message. close_data() ends the email message by sending the sequence "<CR><LF>.<CR><LF>" (a single period at the beginning of a line).
FUNCTION open_data (c IN OUT NOCOPY connection) RETURN reply; PROCEDURE open_data (c IN OUT NOCOPY connection); PROCEDURE write_data (c IN OUT NOCOPY connection, data IN VARCHAR2); PROCEDURE write_raw_data (c IN OUT NOCOPY connection, data IN RAW); FUNCTION close_data (c IN OUT NOCOPY connection) RETURN reply; PROCEDURE close_data (c IN OUT NOCOPY connection);
The SMTP connection.
The portion of the text of the message to be sent, including headers, in [RFC822] format.
The calls to open_data(), write_data(), write_raw_data() and close_data() must be made in the right order. A program calls open_data() to send the DATA command to the SMTP server. After that, it can call write_data() or write_raw_data() repeatedly to send the actual data. The data is terminated by calling close_data(). After, open_data() is called, the only APIs that can be called are write_data(), write_raw_data() or close_data(). A call to other API will result in a INVALID_OPERATION exception being raised.
It is the application's responsibility to ensure that contents of the message parameter conform to the [RFC822] specification. The close_data() routine will terminate the message with a "<CR><LF>.<CR><LF>" sequence (a single period at the beginning of a line), as required by [RFC821]. write_data() will also translate any sequences of "<CR><LF>.<CR><LF>" (single period) in message to "<CR><LF>..<CR><LF>" (double period). This conversion provides the transparency as described in Section 4.5.2 of [RFC821]. Notice that this conversion is not bullet-proof. Consider this code fragment:
utl_smtp.write_data(`some message.' || chr(13) || chr(10)); utl_smtp.write_data(`.' || chr(13) || chr(10));Since the sequence "<CR><LF>.<CR><LF>" is split between 2 calls to
write_data(), the implementation of write_data() will not detect the presence of the data-terminator sequence and, therefore, will not perform the translation. It will be the responsibility of the user to handle such a situation or it may result in pre-mature termination of the message data.XXX_data() should only be called after open_connection(), helo() / ehlo(), mail(), and rcpt()have been called. The connection to the SMTP server must be open and a mail transaction active when this routine is called.Note that there is no function form of write_data() because the SMTP server does not respond until the data-terminator is sent during the call to close_data().Text (VARCHAR2) data sent using write_data() API will be converted to US7ASCII before it is sent. If the text contains multi-byte characters, each multi-byte character in the text that cannot be converted to US7ASCII will be replaced by a `?' character. If 8BITMIME extension is negotiated with the SMTP server using EHLO() API, multi-byte VARCHAR2 data can be sent by first converting the text to RAW using UTL_RAW package and then sending the RAW data using write_raw_data().
Abort the current mail transaction.
FUNCTION rset (c IN OUT NOCOPY connection) RETURN reply; PROCEDURE rset (c IN OUT NOCOPY connection);
The SMTP connection.
This command allows the client to abandon a mail message it was in the process of composing. No mail will be sent. The client can call rset() at any time after the connection to the SMTP server has been opened via open_connection(). The server will always respond to RSET with a message beginning with status code 250.
quit()
Verify the validity of a destination email address.
FUNCTION vrfy (c IN OUT NOCOPY connection, recipient IN VARCHAR2) RETURN reply;
The SMTP connection.
The email address to be verified.
The server attempts to resolve the destination address recipient. If successful, it returns the recipient's full name and fully qualified mailbox path. The connection to the server must have already been established via open_connection() and helo() / ehlo() prior to making this request.
Successful verification returns one or more lines beginning with status codes 250 or 251.
expn()
The null command.
FUNCTION noop (c IN OUT NOCOPY connection) RETURN VARCHAR2; PROCEDURE noop (c IN OUT NOCOPY connection);
The SMTP connection.
This command has no effect except to elicit a successful reply from the server. It can be issued at any time after the connection to the server has been established with open_connection(). The noop() command can be used to verify that the server is still connected and is listening properly.
This command will always reply with a single line beginning with status code 250.
Terminate an SMTP session and disconnect from the server.
Syntax
FUNCTION quit (c IN OUT NOCOPY connection) RETURN VARCHAR2; PROCEDURE quit (c IN OUT NOCOPY connection);
The SMTP connection.
The quit() command informs the SMTP server of the client's intent to terminate the session. It then closes the connection established by open_connection(), which must have been called prior to the execution of this command. If a mail transaction is in progress when quit() is issued, it will be abandoned in the same manner as rset().
The function form of this command will return a single line beginning with the status code 221 on successful termination. In all cases the connection to the SMTP server will be closed. The fields "remote_host" and "remote_port" of p_connection will be reset.
rset()
|
 Copyright © 1996-2000, Oracle Corporation. All Rights Reserved. |
|