| Oracle® Mail Application Developer's Guide 10g Release 1 (10.1.2) Part Number B25459-01 |
|
|
View PDF |
| Oracle® Mail Application Developer's Guide 10g Release 1 (10.1.2) Part Number B25459-01 |
|
|
View PDF |
In recent years a number of applications like order processing, bill payment, and marketing systems rely on email as a mechanism for customer interaction. Since most of these applications already have an Oracle database back-end, they alo benefit greatly by having a PL/SQL SDK for messaging operations. This chapter describes a set of PL/SQL packages with a set of PL/SQL functions and procedures for performing messaging and folder-related tasks like listing folders, retrieving a listing list of messages, and reading and sending messages. The SDK offers the complete set of functionality needed to develop an email client. This chapter describes each of the interfaces and how to use them along with their limitations and restrictions of use.The audience for this chapter includes application developers and client developers who wish to integrate with an Oracle Mail server and write email-enabled applications. The reader is assumed to be familiar with Internet standards for email, such as SMTP, MIME and S/MIME.
The PL/SQL SDK consists of three sets of functionality: Session Management, Folder Operations, and Message Operations.
Session management includes setting up an email server session, authentication, and disconnect. Both simple text-password authentication and strong authentication are supported. Session Management uses and depends on the Directory and Security API for authentication.
Folder functions are all operations for a folder. This includes functions for listing folders and subscription management, as well as creating, deleting, renaming, searching, and sorting on a folder. The second set of folder functions are for manipulating messages in the folder, these are functions for listing messages in the folder, copying messages, saving messages, deleting messages, checking for modifications to the folder, and retrieving new mail.
The Message functions are all operations for a message. This includes functions for reading, composing, sending, and appending messages. To hide the complexity of MIME structure and message encoding, it contains functions to get headers, to get individual body parts, to get body part content, and to construct messages using individual body parts. It also includes S/MIME functionality to verify message signatures, decrypt messages, and send encrypted and/or signed messages.
Concepts
This section discusses the following e-mail related concepts:
Folder UIDL
Message UID
Message Flags
New and Recent Messages
MIME Level
When a folder is created, a validity value is assigned to the folder guaranteeing that as long as the value does not change, the message unique identifier (UID) assigned to the messages in the folder is valid. This value is called folder unique identifier validity (UIDL).
Each message in a folder is assigned a unique identifier validity (UID) value. The UID value persists across sessions, so application may cache these message UID values for message reference in the future. Message UID is always assigned in ascending order in the folder. As each message is added to the folder, it is assigned a higher UID value. The maximum UID permitted is 232 – 1 = 4 billion. Once the maximum has been reached the message UIDs in the folder are re-assigned. The holes in the message UID sequence created by messages deletion are compacted. To reflect this, the folder validity value (Folder UIDL) is changed. When the folder validity value is changed, the application must discard any message UID cache for this folder and re-fetch the message UID values.
Message content cannot be modified, but mail users can change the flag property. When a message is delivered into the user's INBOX folder, the message is not marked with any flag. After the user read a message, the application marks the message with the seen flag.The supported flags are described below:
Table 1-1 Supported Message Flags
| Flag | Description |
|---|---|
|
MAIL_MESSAGE.GC_SEEN_FLAG |
The message has been read |
|
MAIL_MESSAGE.GC_FLAGGED_FLAG |
Marks messages for urgent or special attention |
|
MAIL_MESSAGE.GC_ANSWERED_FLAG |
The message has been replied to |
|
MAIL_MESSAGE.GC_DELETED_FLAG |
The message is marked to be removed later with the expunge command |
|
MAIL_MESSAGE.GC_DRAFT_FLAG |
The message has not completed composition |
New and recent messages only differ when there are multiple client sessions accessing the same mail folder at the same time. A message is considered recent when no other mail client session has retrieved the message. A message is considered new if the current mail user session has not seen the message.
A message MIME level is a string used to identify a specific part of a message. The application does not have to know anything about it. The MIME level is incorporated as part of the message and body-part objects that are passed around. It is for internal use to identify a specific message part.
There are three distinct mail objects in the Oracle Mail Server:
mail account or session
mail folder
mail message
A mail account contains many mail folders. A mail folder contains many mail messages. An INBOX mail folder is a special folder created when the mail user account is created. The INBOX folder cannot be deleted. All incoming messages are delivered into the INBOX folder.
A mail user must be authenticated before performing mail operations. The MAIL_SESSION package provides the functions. When a user is authenticated, a valid session identifier is returned from the authentication routine. This session identifier is passed around to other mail operations that require a valid authenticated session. The mail user session identifier is only valid in the same database session that it has been authenticated in. Multiple mail user sessions are supported so that multiple mail users can authenticate on the same database session. Each authenticated session is associated with a unique identifier.
To access any message in a folder, the user must open the folder. There is only one opened folder in a mail session at any given time. The open folder changes when the folder is closed or another folder is opened.
|
Note: The PL/SQL API contains references todbms_sql.varchar2_table and dbms_sql.number_table types |
|
See Also: The Oracle Supplied Packages Reference manual for the description of these two types. |
The MAIL_FOLDER_OBJ object uniquely identifies a mail folder. It is defined as follows:
MAIL_FOLDER_OBJ(
name VARCHAR2(1024),
id NUMBER
);
MAIL_FOLDER_LIST AS TABLE OF MAIL_FOLDER_OBJ;
name is the full path of the folder name.
id is a unique folder identifier.
MAIL_FOLDER_LIST is a nested table of MAIL_FOLDER_OBJ objects.
The MAIL_FOLDER_DETAIL object contains information pertaining to a specific folder. It is defined as follows:
MAIL_FOLDER_DETAIL (
uidl NUMBER,
num_voice_recent NUMBER,
num_fax_recent NUMBER,
total_recent NUMBER,
num_voice_unseen NUMBER,
num_fax_unseen NUMBER,
total_unseen NUMBER,
total_msgs NUMBER
);
CREATE TYPE MAIL_FOLDER_LIST AS TABLE OF MAIL_FOLDER_OBJ;
The MAIL_FOLDER_DETAIL object contains information on the folder UIDL, number of messages, total number of unseen and recent messages, and number of unseen and recent voice and fax messages.
The MAIL_SORT_CRITERIA_ELEMENT object is used to represent a sort criteria. It is defined as follows:
MAIL_SORT_CRITERIA_ELEMENT(
sort_header VARCHAR2(240),
sort_order INTEGER
);
MAIL_SORT_CRITERIA AS TABLE OF MAIL_SORT_CRITERIA_ELEMENT;
sort_header is the message header used to perform the sort. The supported header names are:
CC
DATE
SUBJECT
SIZE
INTERNAL_DATE
sort_order indicates whether to sort the header field in ascending or descending order. The values are:
MAIL_FOLDER.SORT_ASC
MAIL_FOLDER.SORT_DESC
MAIL_SORT_CRITERIA is a nested table of MAIL_SORT_CRITERIA_ELEMENT objects.
The MAIL_MESSAGE_OBJ object uniquely identifies a mail message. It is defined as follows:
MAIL_MESSAGE_OBJ (
folder_id NUMBER,
msg_uid NUMBER,
mime_level VARCHAR2(240)
);
MAIL_MESSAGE_LIST IS TABLE OF MAIL_MESSGAGE_OBJ;
folder_id is a unique folder identifier
msg_uid uniques identifies a message within the folder.
mime_level either has the value 0 to indicate that this message object is a top-level message, or other value to indicate an included message object.
MAIL_MESSAGE_LIST is a nested table of MAIL_MESSAGE_OBJ objects.
The MAIL_BODYPART_OBJ object uniquely identifes a mail message part. It is defined as follows:
MAIL_BODYPART_OBJ (
content_type VARCHAR2(240),
mime_level VARCHAR2(240),
folder_id NUMBER,
msg_uid NUMBER,
smime_ind NUMBER
);
MAIL_BODYPART_LIST IS TABLE OF MAIL_BODYPART_OBJ;
folder_id is a unique folder identifier.
msg_uid uniquely identifies a message within the folder.
mime_level identifies the specific body-part of the message.
smime_ind is a value of 1 that indicates that the body-part is from a decrypted message.
mail_bodypart_list is a nested table of MAIL_BODYPART_OBJ objects.
The MAIL_MESSAGE_HEADER object identifes a mail message header. It is defined as follows:
MAIL_MESSAGE_HEADER (
msg_uid NUMBER,
from_str VARCHAR2(2000),
subject VARCHAR2(2000),
content_type VARCHAR2(2000),
x_orcl_messagetype VARCHAR2(2000),
x_orcl_mediatype VARCHAR2(2000),
sensitivity VARCHAR2(2000),
importance VARCHAR2(2000)
);
TYPE MAIL_MESSAGE_HEADER_LIST IS TABLE OF MAIL_MESSAGE_HEADER;
msg_uid uniquely identifies a message within the folder.
from_str identifies the "From" part of the header
subject identifies the message subject
content_type is the "Content-type" of the message
x_orcl_messagetype is the X-ORCL-MESSAGETYPE header value
x_orcl_mediatype is the X-ORCL-MEDIATYPE header value
sensitivity is the sensitivity header value
importance is the importance header value
|
Note: This package will no longer be supported from 10.1.1 onwards. Please do not use this package. It will be deprecated in future releases. |
The MAIL_RECOVERY package is provided to recover deleted e-mails, using the Oracle log miner feature.
The redo list file is used by the mail_recovery package to retrieve the list of redo logs. This file must be provided by anadministrator, and can be created manually through a text editor or by outputting a directory list command on UNIX or Windows NT.
The file contains redo log filenames with their full path, and must be listed in separate lines. The redo logs can either be online redo logs, archived logs or both.
It is important to verify that init.ora parameter UTL_FILE_DIR is set to access the redo list file. For example:
/oracle/database/redo01.log /oracle/database/redo02.log /oracle/database/redo03.log
The MAIL_RECOVERY package contains the following procedures:
The setup_logmnr procedure initializes the log miner for recovery.
Syntax
PROCEDURE setup_logmnr(
p_dictionary_filename IN VARCHAR2,
p_redolist_location VARCHAR2,
p_redolist_filename VARCHAR2
p_starttime DATE DEFAULT '01-jan-1988',
p_endtime DATE DEFAULT '01-jan-2099')
Parameters
Table 1-2 SETUP_LOGMNR Procedure
| Parameters | Description |
|---|---|
|
|
Name of the log miner data dictionary file with the full path |
|
|
Directory location of redo list file |
|
|
File name of redo list file |
|
|
Start time of the redo list. Only consider redo records with the time stamp greater than or equal to the start time specified |
|
|
End time of the redo list. Only consider redo records with time stamp less than or equal to the end time specified |
The recover_messages procedure performs the recovery for a user and restores the messages in a specified folder.
Syntax
PROCEDURE recover_messages(
p_domainname IN VARCHAR2,
p_username IN VARCHAR2,
p_foldername IN VARCHAR2,
p_autocommit IN BOOLEAN DEFAULT TRUE);
Parameters
Table 1-3 RECOVER_MESSAGES Procedure
| Parameter | Description |
|---|---|
|
|
Domain name of the user |
|
|
Oracle Mail user name for which recovery is performed |
|
|
Folder name where recovered messages are restored. If NULL, it is passed, and recover_messages creates a new folder with name |
|
|
If True: Frequent commits are performed within |
The MAIL_SESSION package provides user authentication and log out functionality. A user can create multiple mail sessions using the same database session by calling MAIL_SESSION.login()multiple times. Each session ID identifies one valid mail session.
The MAIL_SESSION Package contains the following procedures:
This procedure authenticates a user by user name and password. One of the overloaded versions of this API also accepts an authenticated ES_LOGIN_CONTEXT and returns a mail session identifier.
Throws Exceptions
mail_errors.login_err
Syntax
PROCEDURE login (
user_name IN VARCHAR2,
password IN VARCHAR2,
domain IN VARCHAR2,
ldap_host IN VARCHAR2,
session_id OUT NUMBER,
ldap_port IN NUMBER DEFAULT 389
);
PROCEDURE login (
user_address IN VARCHAR2,
password IN VARCHAR2,
ldap_host IN VARCHAR2,
session_id OUT NUMBER,
ldap_port IN NUMBER DEFAULT 389
);
Parameters
Table 1-4 LOGIN parameters
| Parameter | Description |
|---|---|
|
|
User account name, without the domain part |
|
|
User password |
|
|
User Internet address: user_name@domain |
|
|
User domain |
|
|
The host name where Oracle Internet Directory is configured |
|
|
The port Oracle Internet Directory is listening to; the default is 389 |
|
|
The authenticated |
|
|
An unique identifier that represents this user authenticated session |
This procedure releases all resources associated with this user session.
Syntax
PROCEDURE logout (
session_id IN NUMBER
);
Parameters
Table 1-5 LOGOUT Procedure parameters
| Parameters | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
This procedure returns the current user's usage amount.
Throws Exceptions
mail_errors.unauthenticated_err
Syntax
PROCEDURE get_current_usage (
session_id IN NUMBER,
usage OUT NUMBER
);
Parameters
The MAIL_FOLDER package provides folder-related functionality. The validity of the session is checked before performing any operation. The search and sort features are based on the IMAP4 protocol. The search feature includes Oracle Text based searches.
The MAIL_FOLDER contains the following procedures and functions:
This procedure returns a folder object, given a folder name. If the folder does not exist on the mail store, a FOLDER_NOT_FOUND exception is raised.
Throws Exception
mail_errors.unauthenticated_err
mail_errors.folder_not_found_err
Syntax
PROCEDURE get_folder_obj (
session_id IN NUMBER,
folder_name IN VARCHAR2,
folder_obj OUT MAIL_FOLDER_OBJ
);
Parameters
Table 1-7 GET_FOLDER_OBJ Parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The full path of a folder name. |
|
|
The MAIL_FOLDER_OBJ returned. |
This function returns the folder separator.
Syntax
FUNCTION get_separator return VARCHAR2;
This procedure returns a list of top-level folder objects.
Throws Exceptions
mail_errors.unauthenticated_err
Syntax
PROCEDURE list_toplevel_folders (
session_id IN NUMBER,
folder_list OUT MAIL_FOLDER_LIST
);
Parameters
Table 1-8 LIST_TOPLEVEL_FOLDERS Parameters
| Parameters | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
A list of top-level folder objects |
This procedure returns a list of direct child folder objects, given the parent folder.
Throws Exceptions
mail_errors.unauthenticated_err
mail_errors.folder_not_found_err
Syntax
PROCEDURE list_folders (
session_id IN NUMBER,
parent_name IN VARCHAR2,
folder_list OUT MAIL_FOLDER_LIST
);
PROCEDURE list_folders (
session_id IN NUMBER,
parent_obj IN MAIL_FOLDER_OBJ,
folder_list OUT MAIL_FOLDER_LIST
);
Parameters
Table 1-9 LIST_FOLDERS Parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The full path of the parent folder |
|
|
The MAIL_FOLDER_OBJ representing the parent folder |
|
|
The list of child folder objects under the parent folder |
This procedure returns a list of top-level subscribed folders.
Throws Exception
mail_errors.unauthenticated_err
Syntax
PROCEDURE list_toplevel_subdfldrs (
session_id IN NUMBER,
foldername_list OUT DBMS_SQL.VARCHAR2_TABLE
);
Parameters
Table 1-10 LIST_TOPLEVEL_SUBDFLDRS parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The list of subscribed child folder objects under the parent folder |
This procedure returns a list of subscribed child folders, given the parent folder.
Throws Exceptions
mail_errors.unauthenticated_err
Syntax
PROCEDURE list_subscribed_folders (
session_id IN NUMBER,
parent_name IN VARCHAR2,
foldername_list OUT DBMS_SQL.VARCHAR2_TABLE
);
PROCEDURE list_subscribed_folders (
session_id IN NUMBER,
parent_obj IN MAIL_FOLDER_OBJ,
foldername_list OUT DBMS_SQL.VARCHAR2_TABLE
);
Parameters
Table 1-11 LIST_SUBSCRIBED_FOLDERS Parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The full path of the parent folder name |
|
|
The MAIL_FOLDER_OBJ representing the parent folder |
|
|
The list of subscribed child folder objects under the parent folder |
This function tests to see if the folder is subscribed.
Throws Exceptions
mail_errors.unauthenticated_err
Syntax
FUNCTION is_folder_subscribed (
session_id IN NUMBER,
folder_name IN VARCHAR2
) return BOOLEAN;
Parameters
Table 1-12 IS_FOLDER_SUBSCRIBED parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The full path of the folder name |
This procedure subscribes the specified folder. Errors are not returned if the folder has already been subscribed.
Throws Exceptions
mail_errors.unauthenticated_err
Syntax
PROCEDURE subscribe_folder (
session_id IN NUMBER,
folder_name IN VARCHAR2
);
Parameters
Table 1-13 SUBSCRIBE_FOLDER parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The full path of the folder name |
This procedure unsubscribes the specified folder. Errors are not returned if the folder has not been subscribed at the time of the call.
Throws Exceptions
mail_errors.unauthenticated_err
Syntax
PROCEDURE unsubscribe_folder (
session_id IN NUMBER,
folder_name IN VARCHAR2
);
Parameters
Table 1-14 UNSUBSCRIBE_FOLDER Procedure parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The full path of the folder name |
This function tests to see if any child folders exist.
Throws Exception
mail_errors.unauthenticated_err
Syntax
FUNCTION has_folder_children (
session_id IN NUMBER,
folder_obj IN MAIL_FOLDER_OBJ
) return BOOLEAN;
Parameters
Table 1-15 HAS_FOLDER_CHILDREN Function parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The folder object |
This function returns folder expiry information; specifically, the number of days to keep messages in the folder . A value of 0 means messages will not be automatically removed by the HouseKeeper server.
Throws Exception
mail_errors.unauthenticated_err
Syntax
PROCEDURE get_folder_expiry ( session_id IN NUMBER, folder_name IN VARCHAR2, expiry OUT NUMBER);
Parameters
Table 1-16 GET_FOLDER_EXPIRY Function parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The full path of a folder name |
|
|
Number of days messages will stay in the folder. |
This function sets the folder expiry; specifically, the number of days messages in the folder will be kept. A value of 0 means messages will not be automatically removed by the HouseKeeper server.
Throws Exception
mail_errors.unauthenticated_err
Syntax
PROCEDURE get_folder_expiry ( session_id IN NUMBER, folder_name IN VARCHAR2, expiry OUT NUMBER);
Parameters
Table 1-17 SET_FOLDER_EXPIRY Function parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The full path of a folder name |
|
|
Number of days messages will stay in the folder. |
This procedure returns folder information, such as the folder UIDL identifier, total message count, number of unseen messages, and number of recent messages.
Throws Exceptions
mail_errors.unauthenticated_err
Syntax
PROCEDURE get_folder_details (
session_id IN NUMBER,
folder_obj IN MAIL_FOLDER_OBJ,
folder_detail_obj OUT MAIL_FOLDER_DETAIL
);
Parameters
Table 1-18 GET_FOLDER_DETAILS Parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The folder object |
|
|
A folder detail object that contains information about the folder |
This procedure creates a folder on the mail store with the given name, and returns a folder object representing the new folder. When this folder is created, any folders in its path that don't exist are also created. A FOLDER_TYPE_ERR is returned if the parent folder does not allow creation of subfolders.
Throws Exceptions
mail_errors.unauthenticated_err
mail_errors.folder_already_exists_err
mail_errors.folder_type_err
Syntax
PROCEDURE create_folder (
session_id IN NUMBER,
folder_name IN VARCHAR2,
folder_obj OUT MAIL_FOLDER_OBJ
);
Parameters
Table 1-19 CREATE_FOLDER Parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The full path of a folder name |
|
|
The |
This procedure deletes the specified folder. If a recursive flag is set to true, all the messages in the folder, all sub-folders and their messages, and the folder itself are removed. A recursive flag set to false performs the following actions:
If no sub-folder exists, the messages in the folder and the folder itself are removed.
If sub-folders exist, the messages in the folder are removed, and the folder is marked as not selectable (the OPEN_FOLDER operation on this folder can fail).
If this procedure is called with a folder that is marked as not selectable and contains a subfolder, the MAIL_ERRORS.FOLDER_TYPE_ERR is thrown. If called with folder that has already marked as \NOSELECT and still contains sub-folder, the MAIL_ERRORS.FOLDER_TYPE_ERR will be thrown.
Throws Exceptions
mail_errors.unauthenticated_err
mail_errors.operation_not_allowed
mail_errors.folder_type_err
mail_errors.folder_not_found_err
Syntax
PROCEDURE delete_folder (
session_id IN NUMBER,
folder_name IN VARCHAR2,
recursive IN BOOLEAN DEFAULT false
);
PROCEDURE delete_folder (
session_id IN NUMBER,
folder_obj IN MAIL_FOLDER_OBJ,
recursive IN BOOLEAN DEFAULT false
);
Parameters
Table 1-20 DELETE_FOLDER Parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The full path of the folder name |
|
|
The |
|
|
If set to true, it deletes the folder and any sub-folders |
This procedure renames the specified folder and returns the new folder object. If renaming INBOX, all the messages in INBOX are moved to the new folder name, and the INBOX folder will remain with no messages.
Throws Exceptions
mail_errors.unauthenticated_err
mail_errors.folder_not_found_err
mail_errors.folder_already_exists_err
mail_errors.operation_not_allowed
Syntax
PROCEDURE rename_folder (
session_id IN NUMBER,
folder_name IN VARCHAR2,
new_folder_name IN VARCHAR2,
folder_obj OUT MAIL_FOLDER_OBJ
);
PROCEDURE rename_folder (
session_id IN NUMBER,
folder_obj IN OUT MAIL_FOLDER_OBJ,
new_folder_name IN VARCHAR2
);
Parameters
Table 1-21 RENAME_FOLDER Parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The full path of the folder name |
|
|
The new name for the folder |
|
|
The |
This procedure opens the specified folder and returns the folder object. If the folder is marked with the \NOSELECT flag, a mail_errors.folder_type_err will be thrown.
Throws Exceptions
mail_errors.unauthenticated_err
mail_errors.folder_not_found_err
mail_errors.folder_type_err
Syntax
PROCEDURE open_folder (
session_id IN NUMBER,
folder_name IN VARCHAR2,
folder_obj OUT MAIL_FOLDER_OBJ
);
Parameters
Table 1-22 OPEN_FOLDER Procedure
| Parameters | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The full path of the folder name |
|
|
The |
This procedure returns all of the messages with the specified message type in the current open folder.
Throws Exceptions
mail_errors.unauthenticated_err
mail_errors.folder_closed_err
Syntax
PROCEDURE get_folder_messages (
session_id IN NUMBER,
message_list OUT MAIL_MESSAGE_LIST,
message_type IN NUMBER DEFAULT MAIL_MESSAGE.GC_ALL_MAIL
);
Parameters
Table 1-23 GET_FOLDER_MESSAGES Parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
A list of message objects that belongs to the folder |
|
|
The type of message to be retrieved. The default is to retreive all types. The message types are defined in the Values are:
|
This procedure returns the message object corresponding to the message UID specified in the current open folder.
Throws Exceptions
mail_errors.unauthenticated_err
mail_errors.folder_closed_err
Syntax
PROCEDURE get _message (
session_id IN NUMBER,
message_uid IN NUMBER,
message_obj OUT MAIL_MESSAGE_OBJ
);
Parameters
Table 1-24 GET_MESSAGE Procedure
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The message identifier |
|
|
The |
This procedure closes the current open folder. If the EXPUNGE_FLAG is set to true, all messages in the folder that are marked with the Deleted flag are removed.
Throws Exceptions
mail_errors.unauthenticated_err
mail_errors.folder_closed_err
Syntax
PROCEDURE close_folder (
session_id IN NUMBER,
expunge_flag IN BOOLEAN
);
Parameters
Table 1-25 CLOSE_FOLDER Parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
A flag indicating whether to expunge the folder before closing |
This procedure returns message flags belonging to the message list specified in the current open folder.
Throws Exceptions
mail_errors.unauthenticated_err
mail_errors.folder_closed_err
Syntax
PROCEDURE get_msg_flags (
session_id IN NUMBER,
message_list IN MAIL_MESSAGE_LIST,
message_flags OUT DBMS_SQL.NUMBER_TABLE
);
PROCEDURE get_msg_flags (
session_id IN NUMBER,
message_uid_list IN DBMS_SQL.NUMBER_TABLE,
message_flags OUT DBMS_SQL.NUMBER_TABLE
);
PROCEDURE get_msg_flags (
session_id IN NUMBER,
message_list IN MAIL_MESSAGE_LIST,
message_flags OUT DBMS_SQL.NUMBER_TABLE,
message_usrflags OUT DBMS_SQL.VARCHAR2_TABLE
);
PROCEDURE get_msg_flags (
session_id IN NUMBER,
message_uid_list IN DBMS_SQL.NUMBER_TABLE,
message_flags OUT DBMS_SQL.NUMBER_TABLE,
message_usrflags OUT DBMS_SQL.VARCHAR2_TABLE
);
Parameters
Table 1-26 GET_MSG_FLAGS Parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
A list of message objects that belongs to the folder |
|
|
A list of message UIDs identifying messages in the folder |
|
|
A list of message flags corresponding to the list of requested messages. Flag values are defined in the MAIL_MESSAGE package specification. Values are:
|
|
|
A list of user-defined flags. They are a list of space-separated user-defined flag strings. |
This procedure sets or unsets the message flags belonging to the list of messages specified in the current open folder.
Throws Exceptions
mail_errors.unauthenticated_err
mail_errors.folder_closed_err
Syntax
PROCEDURE set_msg_flags (
session_id IN NUMBER,
message_list IN MAIL_MESSAGE_LIST,
flags IN NUMBER,
set_flag IN BOOLEAN
);
PROCEDURE set_msg_flags (
session_id IN NUMBER,
message_uid_list IN DBMS_SQL.NUMBER_TABLE,
flags IN NUMBER,
set_flag IN BOOLEAN
);
Parameters
Table 1-27 SET_MSG_FLAGS Parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
A list of message objects that belongs to the folder |
|
|
A list of message UIDs identifying messages in the folder |
|
|
A list of message flags corresponding to the list of requested messages. Flag values are defined in the MAIL_MESSAGE package specification. Values are:
|
|
|
If true, sets the value of flags. Otherwise, it unsets the value. |
This procedure toggles user-defined message flags for the specified message object.
Throws Exceptions
mail_errors.unauthenticated_err
mail_errors.folder_closed_err
Syntax
PROCEDURE set_msg_usrflags (
session_id IN NUMBER,
message_obj IN MAIL_MESSAGE_OBJ,
message_usrflags IN VARCHAR2,
set_flag IN BOOLEAN
);
Parameters
Table 1-28 SET_MSG_USRFLAGS Parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The message object |
|
|
User defined message flag string. It contains a list of user defined flag strings separated by space. |
|
|
If true, set the flags specified; otherwise, un-set the flags specified. |
This procedure deletes the list of messages specified in the current open folder. This is equivalent to marking the messages as deleted and performing an expunge operation on the folder.
Throws Exceptions
mail_errors.unauthenticated_err
mail_errors.folder_closed_err
Syntax
PROCEDURE delete_messages (
session_id IN NUMBER,
message_uid_list IN DBMS_SQL.NUMBER_TABLE
);
Parameters
Table 1-29 DELETE_MESSAGES Parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
A list of message UIDs identifying messages in the folder |
This procedure removes all messages in the current open folder if the gc_deleted_flag flag is set.
Throws Exceptions
mail_errors.unauthenticated_err
mail_errors.folder_closed_err
Syntax
PROCEDURE expunge_folder (
session_id IN NUMBER,
);
Parameters
Table 1-30 EXPUNGE_FOLDER Parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
This function tests to see if the folder is the same folder currently selected in the user's session.
Throws Exceptions
mail_errors.unauthenticated_err
Syntax
FUNCTION is_folder_open (
session_id IN NUMBER,
folder_obj IN MAIL_FOLDER_OBJ
) return BOOLEAN;
Parameters
Table 1-31 IS_FOLDER_OPEN parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The folder object |
This function tests to see if there are any new messages in the currently selected folder. New messages are messages not seen by the folder since the last GET_NEW_MESSAGES call. When the folder is first opened, the last message considered retrieved is the message last seen by any mail client. After that the last message is changed accordingly by calls to GET_FOLDER_MESSAGE and GET_NEW_MESSAGES.
Throws Exceptions
mail_errors.unauthenticated_err
mail_errors.folder_closed_err
Syntax
FUNCTION check_new_messages (
session_id IN NUMBER,
message_type IN NUMBER DEFAULT MAIL_MESSAGE.GC_ALL_MAIL
) return BOOLEAN;
Parameters
Table 1-32 CHECK_NEW_MESSAGES Parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The type of message to be retrieved. The default is to get all types. The message types are defined in the MAIL_MESSAGE package specification. |
This function tests to see if there are any recent messages in the specified folder. Recent messages are messages that have not been retrieved by any mail client. This procedure can be called on a closed folder.
Throws Exception
mail_errors.unauthenticated_err
mail_errors.folder_not_found_err
Syntax
FUNCTION check_recent_messages (
session_id IN NUMBER,
folder_name IN VARCHAR2,
message_type IN NUMBER DEFAULT MAIL_MESSAGE.GC_ALL_MAIL
) return BOOLEAN;
Parameters
Table 1-33 CHECK_RECENT_MESSAGES Parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The full path of the folder name |
|
|
The type of message to be retrieved. The default is to retreive all types. Message types are defined in the MAIL_MESSAGE package specification. Values are:
|
This procedure returns all the new messages in the currently selected folder. New messages are messages not seen by the folder since last message retrieval. When the folder is first opened, the last message considered retrieved is the last message seen by any mail client after the last message is changed accordingly by calls to GET_FOLDER_MESSAGES and GET_NEW_MESSAGES. If MESSAGE_TYPE is specified, only messages in the specified type are returned.
Throws Exceptions
mail_errors.unauthenticated_err
mail_errors.folder_closed_err
Syntax
PROCEDURE get_new_messages (
session_id IN NUMBER,
message_list OUT MAIL_MESSAGE_LIST,
message_type IN NUMBER DEFAULT MAIL_MESSAGE.GC_ALL_MAIL
);
Parameters
Table 1-34 GET_NEW_MESSAGES Parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
A list of new message objects |
|
|
The type of message to be retrieved. The default is to retreive all types. Message types are defined in the MAIL_MESSAGE package specification. Values are:
|
This procedure copies messages in the currently selected folder to another folder. If the destination folder has the \NOSELECT flag set, the MAIL_ERRORS.FOLDER_TYPE_ERR exception is thrown. If the specified message does not belong to the current open folder, the MAIL_ERRORS.PARAM_PARSE_ERR exception is thrown.
Throws Exceptions
mail_errors.unauthenticated_err
mail_errors.folder_closed_err
mail_errors.folder_not_found_err
mail_errors.folder_type_err
mail_errors.param_parse_err
Syntax
PROCEDURE copy_messages (
session_id IN NUMBER,
message_list IN MAIL_MESSAGE_LIST,
to_folder_name IN VARCHAR2
);
PROCEDURE copy_messages (
session_id IN NUMBER,
message_uid_list IN DBMS_SQL.NUMBER_TABLE,
to_folder_name IN VARCHAR2
);
Parameters
Table 1-35 COPY_MESSAGES Parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
A list of message objects |
|
|
A list of message UIDs |
|
|
The full path of the destination folder name |
This procedure moves messages in the current folder to another folder. If the destination folder is marked with the \NOSELECT flag (meaning it cannot contain messages), the mail_errors.folder_type err is thrown.
Throws Exceptions
mail_errors.unauthenticated_err
mail_errors.folder_closed_err
mail_errors.folder_not_found_err
mail_errors.folder_type_err
mail_errors.param_parse_err
Syntax
PROCEDURE move_messages (
session_id IN NUMBER,
message_list IN MAIL_MESSAGE_LIST,
to_folder_name IN VARCHAR2
);
PROCEDURE move_messages (
session_id IN NUMBER,
message_uid_list IN DBMS_SQL.NUMBER_TABLE,
to_folder_name IN VARCHAR2
);
PROCEDURE move_messages (
session_id IN NUMBER,
from_folder_obj IN MAIL_FOLDER_OBJECT,
message_uid_list INDBMS_SQL.NUMBER_TABLE,
to_folder_name IN VARCHAR2
);
Parameters
Table 1-36 MOVE_MESSAGES Parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
A list of message objects |
|
|
A list of message UIDs |
|
|
The MAIL_FOLDER_OBJ representing the source folder. |
|
|
The full path of the destination folder name |
This function tests to see if any messages in the currently selected folder have been modified from another session. A folder is modified if any changes in message flags or deletion of messages were made in the folder by another client or session. If the folder was modified, users have to re-issue the GET_NEW_MESSAGES procedure to be synchronized with the mail store.
Throws Exceptions
mail_errors.unauthenticated_err
mail_errors.folder_closed_err
Syntax
FUNCTION is_folder_modified (
session_id IN NUMBER
);
Parameters
Table 1-37 IS_FOLDER_MODIFIED Parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
This procedure sorts the folder given the sort criteria and returns an ordered list of message UIDs.
Throws Exceptions
mail_errors.unauthenticated_err
mail_errors.param_parse_err
Syntax
PROCEDURE sort_folder (
session_id IN NUMBER,
folder_obj IN MAIL_FOLDER_OBJ,
sort_criteria IN MAIL_SORT_CRITERIA,
message_uid_list OUT DBMS_SQL.NUMBER_TABLE
);
PROCEDURE sort_folder (
session_id IN NUMBER,
folder_obj IN MAIL_FOLDER_OBJ,
sort_criteria IN MAIL_SORT_CRITERIA,
message_list OUT MAIL_MESSAGE_LIST);
};
Parameters
Table 1-38 SORT_FOLDER Parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The |
|
|
A list of sort criteria Values are:
|
|
|
An ordered list of message objects |
|
|
An ordered list of message UIDs |
This procedure searches the folder and returns a list of message objects that meet the specified criteria. The format of the search criteria is the same as the format in the IMAP4 protocol [RFC 2060], except when specifying to search within a set of messages, the set is passed in as a parameter.
Examples:
"subject test" (to search for messages with subject containing "test")
"not from abc@domain.com subject deal" (to search for messages not from "abc@domain.com" and subject containing the word "deal")
"or since 22-Oct-2001 larger 50000" (to search for message received on or after 10/22/2001 or messages with size that is greater than 50k).
Throws Exceptions
mail_errors.unauthenticated_err
mail_errors.param_parse_err
Syntax
PROCEDURE search_folder (
session_id IN NUMBER,
folder_obj IN MAIL_FOLDER_OBJ,
search_criteria IN VARCHAR2,
message _list OUT MAIL_MESSAGE_LIST
);
PROCEDURE search_folder (
session_id IN NUMBER,
folder_obj IN MAIL_FOLDER_OBJ,
search_criteria IN VARCHAR2,
in_message_list IN MAIL_MESSAGE_LIST,
message_list OUT MAIL_MESSAGE_LIST
);
Parameters
Table 1-39 SEARCH_FOLDER Parameters
| Parameters | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The |
|
|
A list of search criterion per IMAP4 standard |
|
|
A list of message objects to search from |
|
|
The list of message objects that meets the search criteria |
The MAIL_MESSAGE package provides message retrieval, message composition, and Oracle Text related functionality. The validity of the session is checked before performing any operation, except for composing send operations. Users can only compose one message at a time, and a MSG_COMPOSE_LIMIT_ERR is thrown if a violation occurs.
The MAIL_MESSAGE package contains the following procedures:
This procedure returns a message object given the message UID in the current open folder.
Throws Exceptions
mail_errors.unauthenticated_err
mail_errors.folder_closed_err
Syntax
PROCEDURE get_message_obj (
session_id IN NUMBER,
message_uid IN NUMBER,
message_obj OUT MAIL_MESSAGE_OBJ);
Parameters
Table 1-40 GET_MESSAGE_OBJ Parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The message UID |
|
|
The |
This procedure returns a message object representing the included message. The message type of the specified message or body-part object must be of "message" type; otherwise the MAIL_ERRORS.PARAM_PARSE_ERR exception is thrown.
Throws Exception
mail_errors.unauthenticated_err
mail_errors.param_parse_err
mail_errors.bad_message_var
mail_errors.bad_msgpart_var
Syntax
PROCEDURE get_included_message (
session_id IN NUMBER,
message_obj IN MAIL_MESSAGE_OBJ,
message_obj OUT MAIL_MESSAGE_OBJ);
PROCEDURE get_included_message (
session_id IN NUMBER,
bodypart_obj IN MAIL_BODYPART_OBJ,
message_obj IN MAIL_MESSAGE_OBJ,
);
Parameters
Table 1-41 GET_INCLUDED_MESSAGE Parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The message object with message Content-Type |
|
|
The body-part object with message Content-Type |
|
|
The |
This procedure returns the corresponding header value given in the header prompt.
If a message object is passed in, the header value refers to the top-level message header.
If a body-part object is passed in, the header value refers to that specific body-part header.
When the header prompt is not found in the headers, a null value is returned. When the returned value is a VARCHAR2 type, it is truncated to a maximum length of 2000. If there are multiple headers with the same prompt, the returned value is the first header. When the returned value is a MAIL_HEADER_LIST object list, all headers with the specified prompt name are returned.
Throws Exceptions
mail_errors.unauthenticated_err
mail_errors.bad_message_var
mail_errors.bad_msgpart_var
Syntax
PROCEDURE get_header (
session_id IN NUMBER,
message_obj IN MAIL_MESSAGE_OBJ,
header_prompt IN VARCHAR2,
header_value OUT VARCHAR2);
PROCEDURE get_header (
session_id IN NUMBER,
bodypart_obj IN MAIL_BODYPART_OBJ,
header_prompt IN VARCHAR2,
header_value OUT VARCHAR2);
PROCEDURE get_header (
session_id IN NUMBER,
message_obj IN MAIL_MESSAGE_OBJ,
header_list OUT MAIL_HEADER_LIST);
PROCEDURE get_header (
session_id IN NUMBER,
bodypart_obj IN MAIL_BODYPART_OBJ,
header_list OUT MAIL_HEADER_LIST);
Parameters
Table 1-42 GET_HEADER Parameters
| Parameters | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The message object |
|
|
The body-part object |
|
|
The message header |
|
|
The corresponding header value |
|
|
A list of header objects with the specified prompt |
This procedure returns all of the header values of the given message part. If a message object is passed in, the header value refers to the top-level message header.
If a body-part object is passed in, the header value is referred to that specific body-part header.
When the returned value is a dbms_sql.varchar2_table type, all header values are truncated to 2000 in length if the length of the value is longer than 2000. When the headers are returned in a MAIL_HEADER_LIST object list, each name and value pair is represented by a MAIL_HEADER_OBJ object.
Throws Exception
mail_errors.unauthenticated_err
mail_errors.bad_message_var
mail_errors.bad_msgpart_var
Syntax
PROCEDURE get_headers (
session_id IN NUMBER,
message_obj IN MAIL_MESSAGE_OBJ,
header_prompts IN dbms_sql.varchar2_table,
header_values OUT dbms_sql.varchar2_table);
PROCEDURE get_headers (
session_id IN NUMBER,
bodypart_obj IN MAIL_BODYPART_OBJ,
header_prompts IN dbms_sql.varchar2_table,
header_values OUT dbms_sql.varchar2_table);
PROCEDURE get_headers (
session_id IN NUMBER,
message_obj IN MAIL_MESSAGE_OBJ,
header_list OUT MAIL_HEADER_LIST);
PROCEDURE get_headers (
session_id IN NUMBER,
bodypart_obj IN MAIL_BODYPART_OBJ,
header_list OUT MAIL_HEADER_LIST);
Parameters
Table 1-43 GET_HEADERS Parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The message object |
|
|
The body-part object |
|
|
An array of header names belonging to this part |
|
|
An array of corresponding header values |
|
|
A list of header objects belonging to this part |
This procedure is used to obtain the Content-Type header value. It internally calls the GET_HEADER procedure with the specific header prompt.
Throws Exceptions
mail_errors.unauthenticated_err
mail_errors.bad_message_var
mail_errors.bad_msgpart_var
Syntax
PROCEDURE get_content_type (
session_id IN NUMBER,
message_obj IN MAIL_MESSAGE_OBJ,
content_type OUT VARCHAR2);
PROCEDURE get_content_type (
session_id IN NUMBER,
bodypart_obj IN MAIL_BODYPART_OBJ,
content_type OUT VARCHAR2);
Parameters
Table 1-44 GET_CONTENT_TYPE Parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The message object |
|
|
The body-part object |
|
|
The Content-Type header value |
This procedure is used to obtain the Reply-To header value. It internally calls the GET_HEADER procedure with the specific header prompt.
Throws Exception
mail_errors.unauthenticated_err
mail_errors.bad_message_var
mail_errors.bad_msgpart_var
Syntax
PROCEDURE get_reply_to (
session_id IN NUMBER,
message_obj IN MAIL_MESSAGE_OBJ,
replyTo_str OUT VARCHAR2);
Parameters
Table 1-45 GET_REPLY_TO Parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The message object |
|
|
The Reply-To header value |
This procedure is used to obtain the Date header value. It internally calls the GET_HEADER procedure with the specific header prompt.
Throws Exceptions
mail_errors.unauthenticated_err
mail_errors.bad_message_var
mail_errors.bad_msgpart_var
Syntax
PROCEDURE get_sent_date (
session_id IN NUMBER,
message_obj IN MAIL_MESSAGE_OBJ,
sent_date OUT VARCHAR2);
Parameters
Table 1-46 GET_SENT_DATE Parameters
| Parameters | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The message object |
|
|
The Date header value |
This procedure is used to obtain the Subject header value. It internally calls the GET_HEADER procedure with the specific header prompt.
Throws Exceptions
mail_errors.unauthenticated_err
mail_errors.bad_message_var
mail_errors.bad_msgpart_var
Syntax
PROCEDURE get_subject (
session_id IN NUMBER,
message_obj IN MAIL_MESSAGE_OBJ,
subject_str OUT VARCHAR2);
Parameters
Table 1-47 GET_SUBJECT Parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The message object |
|
|
The subject header value |
This procedure is used to obtain the From header value. It internally calls the GET_HEADER procedure with the specific header prompt.
Throws Exceptions
mail_errors.unauthenticated_err
mail_errors.bad_message_var
mail_errors.bad_msgpart_var
Syntax
PROCEDURE get_from (
session_id IN NUMBER,
message_obj IN MAIL_MESSAGE_OBJ,
from_str OUT VARCHAR2);
Parameters
Table 1-48 GET_FROM Parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The message object |
|
|
The From header value |
This procedure is used to obtain the Message-ID header value. It internally calls the GET_HEADER procedure with the specific header prompt.
Throws Exception
mail_errors.unauthenticated_err
mail_errors.bad_message_var
mail_errors.bad_msgpart_var
Syntax
PROCEDURE get_messageID (
session_id IN NUMBER,
message_obj IN MAIL_MESSAGE_OBJ,
messageID_str OUT VARCHAR2);
Parameters
Table 1-49 GET_MESSAGEID Parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The message object |
|
|
The Message-ID header value |
This procedure is used to obtain the Content-ID header value. It internally calls the GET_HEADER procedure with the specific header prompt.
Throws Exceptions
mail_errors.unauthenticated_err
mail_errors.bad_message_var
mail_errors.bad_msgpart_var
Syntax
PROCEDURE get_contentID (
session_id IN NUMBER,
bodypart_obj IN MAIL_BODYPART_OBJ,
contentID_str OUT VARCHAR2);
Parameters
Table 1-50 GET_CONTENTID Parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The body-part object |
|
|
The Content-ID header value |
This procedure is used to obtain the Content-Language header value. It internally calls the GET_HEADER procedure with the specific header prompt.
Throws Exceptions
mail_errors.unauthenticated_err
mail_errors.bad_message_var
mail_errors.bad_msgpart_var
Syntax
PROCEDURE get_contentLang (
session_id IN NUMBER,
bodypart_obj IN MAIL_BODYPART_OBJ,
language OUT VARCHAR2);
Parameters
Table 1-51 GET_CONTENTLANG Parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The body-part object |
|
|
The Content-Language header value |
This procedure is used to obtain the Content-MD5 header value. It internally calls the GET_HEADER procedure with the specific header prompt.
Throws Exceptions
mail_errors.unauthenticated_err
mail_errors.bad_message_var
mail_errors.bad_msgpart_var
Syntax
PROCEDURE get_contentMD5 (
session_id IN NUMBER,
bodypart_obj IN MAIL_BODYPART_OBJ,
md5 OUT VARCHAR2);
Parameters
Table 1-52 GET_CONTENTMD5 Parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The body-part object |
|
|
The Content-MD5 header value |
This procedure is used to obtain the Content-Type header value, and extract the CHARSET attribute value. It internally calls the GET_HEADER procedure with the specific header prompt.
Throws Exceptions
mail_errors.unauthenticated_err
mail_errors.bad_message_var
mail_errors.bad_msgpart_var
Syntax
PROCEDURE get_charset (
session_id IN NUMBER,
bodypart_obj IN MAIL_BODYPART_OBJ,
charset OUT VARCHAR2);
Parameters
Table 1-53 GET_CHARSET Parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The body-part object |
|
|
The character set attribute value |
This procedure is used to obtain the Content-Disposition header value. It internally calls the GET_HEADER procedure with the specific header prompt.
Throws Exceptions
mail_errors.unauthenticated_err
mail_errors.bad_message_var
mail_errors.bad_msgpart_var
Syntax
PROCEDURE get_contentDisp (
session_id IN NUMBER,
bodypart_obj IN MAIL_BODYPART_OBJ,
disposition OUT VARCHAR2);
Parameters
Table 1-54 GET_CONTENTDISP Parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The body-part object |
|
|
The Content-Disposition header value |
This procedure is used to obtain the Content-Transfer-Encoding header value. It internally calls the GET_HEADER procedure with the specific header prompt.
Throws Exceptions
mail_errors.unauthenticated_err
mail_errors.bad_message_var
mail_errors.bad_msgpart_var
Syntax
PROCEDURE get_encoding (
session_id IN NUMBER,
message_obj IN MAIL_MESSAGE_OBJ,
encoding OUT VARCHAR2);
PROCEDURE get_encoding (
session_id IN NUMBER,
bodypart_obj IN MAIL_BODYPART_OBJ,
encoding OUT VARCHAR2);
Parameters
Table 1-55 GET_ENCODING Parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The message object |
|
|
The body-part object |
|
|
The Content-Transfer-Encoding header value |
This procedure is used to obtain the Content-Disposition header value and extract the filename attribute value. It internally calls the GET_HEADER procedure with the specific header prompt.
Throws Exceptions
mail_errors.unauthenticated_err
mail_errors.bad_message_var
mail_errors.bad_msgpart_var
Syntax
PROCEDURE get_content_filename (
session_id IN NUMBER,
bodypart_obj IN MAIL_BODYPART_OBJ,
filename OUT VARCHAR2);
Parameters
Table 1-56 GET_CONTENT_FILENAME Parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The body-part object |
|
|
The filename attribute value |
This procedure returns the message size.
Throws Exceptions
mail_errors.unauthenticated_err
Syntax
PROCEDURE get_msg_id (
session_id IN NUMBER,
message_obj IN MAIL_MESSAGE_OBJ,
message_size OUT NUMBER);
Parameters
Table 1-57 GET_MSG_SIZE Parameters
| Parameters | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The message object |
|
|
The message size |
This procedure is used to obtain the time the message is received at the mail store.
Throws Exceptions
mail_errors.unauthenticated_err
mail_errors.bad_message_var
mail_errors.bad_msgpart_var
Syntax
PROCEDURE get_rcvd_date (
session_id IN NUMBER,
message_obj IN MAIL_MESSAGE_OBJ,
date_format IN VARCHAR2,
date_str OUT VARCHAR2);
PROCEDURE get_rcvd_date (
session_id IN NUMBER,
message_obj IN MAIL_MESSAGE_OBJ,
received_date OUT DATE);
Parameters
Table 1-58 GET_RCVD_DATE Parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The message object |
|
|
The date to string format |
|
|
The received date in the string format specified |
|
|
The received date in Oracle date format |
This procedure returns the size of the body-part.
Throws Exceptions
mail_errors.unauthenticated_err
mail_errors.bad_message_var
Syntax
PROCEDURE get_bodypart_size (
session_id IN NUMBER,
bodypart_obj IN MAIL_BODYPART_OBJ,
bodypart_size OUT NUMBER);
Parameters
Table 1-59 GET_BODYPART_SIZE Parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The body-part object |
|
|
The body-part size |
This procedure returns the line count of the body-part.
Throws Exceptions
mail_errors.unauthenticated_err
mail_errors.bad_message_var
Syntax
PROCEDURE get_content_linecount (
session_id IN NUMBER,
bodypart_obj IN MAIL_BODYPART_OBJ,
line_count OUT NUMBER);
Parameters
Table 1-60 GET_CONTENT_LINECOUNT Parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The body-part object |
|
|
The total number of lines in the body-part |
This procedure returns a list of body-parts that belong to the specified multipart message or body-part. If the message or body-part object passed in is not of a multipart MIME type, a PARAM_PARSE_ERR exception is raised.
Throws Exceptions
mail_errors.unauthenticated_err
mail_errors.param_parse_err
mail_errors.bad_message_var
Syntax
PROCEDURE get_multipart_bodyparts (
session_id IN NUMBER,
message_obj IN MAIL_MESSAGE_OBJ,
bodypart_list OUT MAIL_BODYPART_LIST);
PROCEDURE get_multipart_bodyparts (
session_id IN NUMBER,
bodypart_obj IN MAIL_BODYPART_OBJ,
bodypart_list OUT MAIL_BODYPART_LIST);
Parameters
Table 1-61 GET_MULTIPART_BODYPARTS Parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The message object |
|
|
The body-part object |
|
|
A list of body-parts |
This procedure returns a BLOB locator to the entire encoded message. Storage does not needs to be allocated beforehand.
Throws Exceptions
mail_errors.unauthenticated_err
Syntax
PROCEDURE get_msg (
session_id IN NUMBER,
message_obj IN MAIL_MESSAGE_OBJ,
message_source OUT BLOB);
Parameters
Table 1-62 GET_MSG Parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The message object |
|
|
The whole message content in its original encoded form |
This procedure copies the message body into the specified BLOB locator. The locator must have enough storage for the data. If the message is not a simple MIME type, no data is returned. If the message body's Content-Transfer-Encoding header specifies that the data is encoded, using base64 or quoted-printable encodings, the content is decoded before returning.
Throws Exceptions
mail_errors.unauthenticated_err
mail_errors.bad_message_var
Syntax
PROCEDURE get_msg_body (
session_id IN NUMBER,
message_obj IN MAIL_MESSAGE_OBJ,
content OUT BLOB);
Parameters
Table 1-63 GET_MSG_BODY Parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The message object |
|
|
The entire decoded message content |
This procedure copies the content of the body-part into the specified BLOB locator. If the body-part object is not a simple MIME type, no data is returned. If the body-part's Content-Transfer-Encoding header specifies that the data is encoded, using base64 or quoted-printable encodings, the content is decoded before returning.
Throws Exceptions
mail_errors.unauthenticated_err
mail_errors.bad_message_var
Syntax
PROCEDURE get_bodypart_content (
session_id IN NUMBER,
bodypart_obj IN MAIL_BODYPART_OBJ,
content OUT BLOB);
Parameters
Table 1-64 GET_BODYPART_CONTENT
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The body-part object |
|
|
The entire decoded message content |
This procedure returns the flags associated with a message.
Throws Exceptions
mail_errors.unauthenticated_err
mail_errors.folder_closed_err
Syntax
PROCEDURE get_msg_flags (
session_id IN NUMBER,
message_obj IN MAIL_MESSAGE_OBJ,
message_flags OUT NUMBER);
PROCEDURE get_msg_flags (
session_id IN NUMBER,
message_obj IN MAIL_MESSAGE_OBJ,
message_flags OUT NUMBER,
message_usrflags OUT VARCHAR2
);
Parameters
Table 1-65 GET_MSG_FLAGS Parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
A message object |
|
|
The message flags are a set of well-defined bit-wise values. The bits are defined in the MAIL_MESSAGE package specification. |
|
|
User defined message flag string. It contains a list of user defined flag strings separated by spaces. |
This procedure sets and unsets the message flags for the specified message object.
Throws Exceptions
mail_errors.unauthenticated_err
mail_errors.folder_closed_err
Syntax
PROCEDURE set_msg_flags (
session_id IN NUMBER,
message_obj IN MAIL_MESSAGE_OBJ,
message_flags IN NUMBER,
set_flag IN BOOLEAN);
Parameters
Table 1-66 SET_MSG_FLAGS Parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
A message object |
|
|
The message flags are a set of well-defined bit-wise values. The bits are defined in the MAIL_MESSAGE package specification. |
|
|
If true, sets the specified flags, otherwise, unsets the specified flags |
This procedure returns authenticated user information, if available. The authenticated user information is stored when a user authenticates before sending an e-mail.
Throws Exceptions
mail_errors.unauthenticated_err
Syntax
PROCEDURE get_auth_info (
session_id IN NUMBER,
message_obj IN MAIL_MESSAGE_OBJ,
auth_info OUT VARCHAR2);
Parameters
Table 1-67 GET_AUTH_INFO Parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The message object |
|
|
The authenticated user information |
A comment is a name-value pair. If the specified comment name is set for the message, this procedure returns the comment value.
Throws Exceptions
mail_errors.unauthenticated_err
mail_errors.folder_closed_err
Syntax
PROCEDURE get_msg_comment (
session_id IN NUMBER,
message_obj IN MAIL_MESSAGE_OBJ,
comment_name IN VARCHAR2,
comment_value OUT VARCHAR2
);
Parameters
Table 1-68 GET_MSG_COMMENT Parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The message object |
|
|
The name of the comment. |
|
|
The returned value of the comment. |
A comment is a name-value pair. If the specified comment name is set for the message, this procedure returns the comment value.
Throws Exceptions
mail_errors.unauthenticated_err
mail_errors.folder_closed_err
Syntax
PROCEDURE set_msg_comment (
session_id IN NUMBER,
message_obj IN MAIL_MESSAGE_OBJ,
comment_name IN VARCHAR2,
comment_value IN VARCHAR2
);
Parameters
Table 1-69 SET_MSG_COMMENT Parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The message object |
|
|
The name of the comment. |
|
|
The new value of the comment. |
This procedure sets a list of comments (name-value pairs) for the message.
Throws Exceptions
mail_errors.unauthenticated_err
mail_errors.folder_closed_err
Syntax
PROCEDURE set_msg_comments (
session_id IN NUMBER,
message_obj IN MAIL_MESSAGE_OBJ,
comment_names IN dbms_sql.varchar2_table,
comment_values IN dbms_sql.varchar2_table
);
Parameters
Table 1-70 SET_MSG_COMMENTS Parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The message object |
|
|
The names of the comment. |
|
|
The new values of the comments. |
This procedure removes a message comment (a name-value pair) given the comment name.
Throws Exceptions
mail_errors.unauthenticated_err
mail_errors.folder_closed_err
Syntax
PROCEDURE remove_msg_comment (
session_id IN NUMBER,
message_obj IN MAIL_MESSAGE_OBJ,
comment_name IN VARCHAR2,
);
Parameters
Table 1-71 REMOVE_MSG_COMMENT Parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The message object |
|
|
The name of the comment to remove |
This procedure removes a list of message comments (name-value pairs) given the comment names.
Throws Exceptions
mail_errors.unauthenticated_err
mail_errors.folder_closed_err
Syntax
PROCEDURE remove_msg_comments (
session_id IN NUMBER,
message_obj IN MAIL_MESSAGE_OBJ,
comment_names IN dbms_sql.varchar2_table,
);
Parameters
Table 1-72 REMOVE_MSG_COMMENTS Parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The message object |
|
|
The names of the comments to delete |
This procedure initializes a message composition. There can be at most one message in composition at any given time.
Throws Exceptions
mail_errors.msg_compose_limit_err
mail_errors.param_parse_err
Syntax
PROCEDURE compose_message (
message_obj OUT MAIL_MESSAGE_OBJ);
Parameters
This procedure sets a list of common message headers. If null is specified, the header is not included. If the sent date is null, it is set to the current time.
Throws Exceptions
mail_errors.msg_compose_limit_err
Syntax
PROCEDURE set_msgheader (
message_obj IN MAIL_MESSAGE_OBJ,
to_str IN VARCHAR2,
from_str IN VARCHAR2,
cc_str IN VARCHAR2 DEFAULT null,
replyto_str IN VARCHAR2 DEFAULT null,
sent_date IN DATE DEFAULT null,
subject_str IN VARCHAR2 DEFAULT null,
mime_version IN VARCHAR2 DEFAULT '1.0',
content_type IN VARCHAR2 DEFAULT 'text/plain',
charset IN VARCHAR2 DEFAULT 'us-ascii',
encoding IN VARCHAR2 DEFAULT '8bit');
Parameters
Table 1-74 SET_MSGHEADER Parameters
| Parameter | Description |
|---|---|
|
|
A message object |
|
|
The To RFC822 header |
|
|
The From RFC822 header |
|
|
The Cc RFC822 header |
|
|
The Reply-to RFC822 header |
|
|
The Date RFC822 header |
|
|
The Subject RFC822 header |
|
|
The MIME-Version RFC822 header |
|
|
The Content-Type RFC822 header |
|
|
The Content-Type RFC822 header charset attribute |
|
|
The Content-Transfer-Encoding RFC822 header |
This procedure sets a list of common body-part headers. If null is specified, the header is not included. All header values are limited to 2000 in length; if it exceeds the limit, a MAIL_ERRORS.PARAM_PARSE_ERR is thrown.
Throws Exceptions
mail_errors.msg_compose_limit_err
mail_errors.param_parse_err
Syntax
PROCEDURE set_bpheader (
bodypart_obj IN MAIL_BODYPART_OBJ,
content_type IN VARCHAR2 DEFAULT 'text/plain',
charset IN VARCHAR2 DEFAULT 'us-ascii',
encoding IN VARCHAR2 DEFAULT '8bit',
contentID IN VARCHAR2 DEFAULT null,
language IN VARCHAR2 DEFAULT null,
contentMD5 IN VARCHAR2 DEFAULT null,
description IN VARCHAR2 DEFAULT null,
disposition IN VARCHAR2 DEFAULT 'inline',
filename IN VARCHAR2 DEFAULT null);
Parameters
Table 1-75 SET_BPHEADER Parameters
| Parameter | Description |
|---|---|
|
|
A message object |
|
|
The Content-Type header |
|
|
The Content-Type header charset attribute |
|
|
The Content-Transfer-Encoding header |
|
|
The Content-ID header |
|
|
The Content-Language header |
|
|
The Content-MD5 header |
|
|
The Content-Description header |
|
|
The Content-Disposition header |
|
|
The Content-Disposition header filename attribute |
This procedure sets the header value, given the header prompt. This does not override any previous headers; it adds to them. All header values are limited to 2000 in length; if it exceeds the limit, a MAIL_ERRORS.PARAM_PARSE_ERR is thrown.
Throws Exceptions
mail_errors.msg_compose_limit_err
mail_errors.param_parse_err
Syntax
PROCEDURE set_header (
message_obj IN MAIL_MESSAGE_OBJ,
header_prompt IN VARCHAR2,
header_value IN VARCHAR2);
PROCEDURE set_header (
bodypart_obj IN MAIL_BODYPART_OBJ,
header_prompt IN VARCHAR2,
header_value IN VARCHAR2);
Parameters
Table 1-76 SET_HEADER Parameters
| Parameter | Description |
|---|---|
|
|
The message object |
|
|
The body-part object |
|
|
The message or body-part header |
|
|
The corresponding header value |
This procedure adds a child body-part to the specified parent message or body-part of Content-Type multipart. If the parent message or body-part object does not have "message" content-type, a PARAM_PARSE_ERR exception is thrown.
Throws Exceptions
mail_errors.msg_compose_limit_err
mail_errors.param_parse_err
Syntax
PROCEDURE add_bodypart (
parent_message_obj IN MAIL_MESSAGE_OBJ,
bodypart_obj OUT MAIL_BODYPART_OBJ);
PROCEDURE add_bodypart (
parent_bodypart_obj IN MAIL_BODYPART_OBJ,
bodypart_obj OUT MAIL_BODYPART_OBJ);
Parameters
Table 1-77 ADD_BODYPART Parameters
| Parameter | Description |
|---|---|
|
|
The parent message object |
|
|
The parent body-part object |
|
|
The new child body-part object returned |
This procedure adds a new included message to the specified parent message or body-part of Content-Type message. If the parent message or body-part object does not have "message" content-type, a PARAM_PARSE_ERR exception is thrown.
Throws Exceptions
mail_errors.msg_compose_limit_err
mail_errors.param_parse_err
Syntax
PROCEDURE add_inclmsg_bodypart (
parent_message_obj IN MAIL_MESSAGE_OBJ,
message_obj OUT MAIL_MESSAGE_OBJ);
PROCEDURE add_inclmsg_bodypart (
parent_bodypart_obj IN MAIL_BODYPART_OBJ,
message_obj OUT MAIL_MESSAGE_OBJ);
Parameters
Table 1-78 ADD_INCLMSG_BODYPART Parameters
| Parameter | Description |
|---|---|
|
|
The parent message object |
|
|
The parent body-part object |
|
|
The new included message object returned |
This procedure sets an included message to the specified parent message or body-part of Content-Type message. The included message must already exist in the mail store. If the parent message or body-part object does not have "message" content-type, a PARAM_PARSE_ERR exception is thrown.
Throws Exceptions
mail_errors.msg_compose_limit_err
mail_errors.param_parse_err
Syntax
PROCEDURE set_inclmsg_bodypart (
parent_message_obj IN MAIL_MESSAGE_OBJ,
message_obj IN MAIL_MESSAGE_OBJ);
PROCEDURE set_inclmsg_bodypart (
parent_bodypart_obj IN MAIL_BODYPART_OBJ,
message_obj IN MAIL_MESSAGE_OBJ);
Parameters
Table 1-79 SET_INCLMSG_BODYPART
| Parameter | Description |
|---|---|
|
|
The parent message object |
|
|
The parent body-part object |
|
|
An existing message in mail store |
This procedure sets the message or body-part content for the message in the composition. If the message or body-part is not a simple MIME type, a PARAM_PARSE_ERR is thrown. This procedure can be called multiple times. The data is connected together. The data should be in decoded form. When the composed message is sent or appended, the data is encoded according to the Content-Transfer-Encoding header specified for this part of the data.
Throws Exceptions
mail_errors.msg_compose_limit_err
mail_errors.param_parse_err
Syntax
PROCEDURE set_content (
message_obj IN MAIL_MESSAGE_OBJ,
content IN RAW);
PROCEDURE set_content (
message_obj IN MAIL_MESSAGE_OBJ,
content IN BLOB);
PROCEDURE set_content (
bodypart_obj IN MAIL_BODYPART_OBJ,
content IN RAW);
PROCEDURE set_content (
bodypart_obj IN MAIL_BODYPART_OBJ,
content IN BLOB);
Parameters
Table 1-80 SET_CONTENT Parameters
| Parameter | Description |
|---|---|
|
|
The message object |
|
|
The body-part object |
|
|
The message or body-part content |
This procedure sends the message currently in composition. The message can also be sent encrypted, signed, or both.
Throws Exceptions
mail_errors.msg_compose_limit_err
mail_errors.smime_err
Syntax
PROCEDURE send_message (
message_obj IN MAIL_MESSAGE_OBJ);
PROCEDURE send_message (
message_obj IN MAIL_MESSAGE_OBJ,
ceritificate IN RAW,
private_key IN RAW,
recipients IN MAIL_MESSAGE.RAW_TABLE,
inclOrigCert IN BOOLEAN,
inclOrigAsRecip IN BOOLEAN,
digest_algorithm IN BINARY_INTEGER,
sign_algorithm IN BINARY_INTEGER,
encrypt_algorithm IN BINARY_INTEGER,
send_option IN NUMBER);
Parameters
Table 1-81 SEND_MESSAGE Parameters
| Parameter | Description |
|---|---|
|
|
The message object |
|
|
The user's certificate |
|
|
The user's private key |
|
|
The recipient's certificates |
|
|
Specifies whether to include the user's certificate when encrypting, signing, or both |
|
|
Specifies whether to include the user's certificate in the recipient list |
|
|
The algorithm to use for generating the digest when signing. It is not used if the message is only being encrypted Values are:
|
This procedure appends the current message composition to the specified folder. The user must be authenticated and the folder must belong to the user.
Throws Exceptions
mail_errors.unauthenticated_err
mail_errors.msg_compose_limit_err
Syntax
PROCEDURE append_message (
session_id IN NUMBER,
message_obj IN MAIL_MESSAGE_OBJ,
folder_name IN VARCHAR2,
received_date IN DATE DEFAUL null,
message_flags IN NUMBER DEFAULT 0);
PROCEDURE append_message (
session_id IN NUMBER,
message_obj IN MAIL_MESSAGE_OBJ,
folder_obj IN MAIL_FOLDER_OBJ,
received_date IN DATE DEFAUL null,
message_flags IN NUMBER DEFAULT 0);
Parameters
Table 1-82 APPEND_MESSAGE Parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The message object |
|
|
The folder to which the message is appended |
|
|
The folder to which the message is appended |
|
|
The message's received date |
|
|
A list of message flags corresponding to the list of requested messages. Flag values are defined in the MAIL_MESSAGE package specification. Values are:
|
This procedure aborts the current message in composition, and cleans up current message information. This procedure should be called for any errors during message composition.
Syntax
PROCEDURE abort_message;
This utility function can be used to encode a non-ASCII string into an RFC2047 formatted header string. If the string passed in is ASCII, the function returns the string as is.
Throws Exceptions
mail_errors.msg_compose_limit_err
Syntax
FUNCTION encode_hdrtext (
p_string IN VARCHAR2
) RETURNS VARCHAR2;
Parameters
This procedure decrypts a S/MIME message and returns a list of body-parts that belongs to the encrypted part.
Throws Exceptions
mail_errors.unauthenticated_err
mail_errors.smime_err
Syntax
PROCEDURE decrypt_message (
session_id IN NUMBER,
message_obj IN MAIL_MESSAGE_OBJ,
ceritificate IN RAW,
private_key IN RAW,
bodypart_list OUT MAIL_BODYPART_LIST
);
PROCEDURE decrypt_message (
session_id IN NUMBER,
bodypart_obj IN MAIL_MESSAGE_OBJ,
ceritificate IN RAW,
private_key IN RAW,
bodypart_list OUT MAIL_BODYPART_LIST
);
Parameters
Table 1-84 DECRYPT_MESSAGE Parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The message object |
|
|
The body-part message |
|
|
The user's certificate |
|
|
The user's private key |
|
|
The decrypted body-part list |
This procedure verifies a digitally signed message.
Throws Exceptions
mail_errors.unauthenticated_err
mail_errors.smime_err
Syntax
PROCEDURE verify_message (
session_id IN NUMBER,
ceritificate IN RAW,
private_key IN RAW,
original_content IN BLOB,
certificate_list IN ES_CERT_LIST,
signature IN BLOB,
returned_content OUT BLOB
);
Parameters
Table 1-85 VERIFY_MESSAGE Parameters
| Parameters | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The user's certificate |
|
|
The user's private key |
|
|
The message content |
|
|
The certificate list |
|
|
The digitally signed signature |
This procedure retrieves the theme for the message or body-part. If a message object is specified, the entire message is processed. If a body-part object is specified, the part must be a simple type and not contain any other body-parts.
Throws Exceptions
mail_errors.unauthenticated_err
mail_errors.sql_err
mail_errors.imt_err
mail_errors.bad_message_var
mail_errors.bad_msgpart_var
mail_errors.no_binary_err
Syntax
PROCEDURE get_themes (
session_id IN NUMBER,
message_obj IN MAIL_MESSAGE_OBJ,
flags IN INTEGER,
incl_binary_parts IN BOOLEAN,
theme_buffer OUT ES_OT_API.THEME_TABLE);
PROCEDURE get_themes (
session_id IN NUMBER,
bodypart_obj IN MAIL_BODYPART_OBJ,
flags IN INTEGER,
incl_binary_parts IN BOOLEAN,
theme_buffer OUT ES_OT_API.THEME_TABLE);
Parameters
Table 1-86 GET_THEMES Parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The message object |
|
|
The body-part object |
|
|
Currently not used |
|
|
If false, the non-text part is ignored |
|
|
The theme buffer |
This procedure retrieves the highlights for the message or body-part. If a message object is specified, the entire message is processed. If a body-part object is specified, the part must be a simple type and not contain any other body-parts.
Throws Exceptions
mail_errors.unauthenticated_err
mail_errors.sql_err
mail_erros.imt_err
mail_errors.bad_message_var
mail_errors.bad_msgpart_var
mail_errors.no_binary_err
Syntax
PROCEDURE get_highlight (
session_id IN NUMBER,
message_obj IN MAIL_MESSAGE_OBJ,
flags IN INTEGER,
text_query IN VARCHAR2,
incl_binary_parts IN BOOLEAN,
highlight_buffer OUT ES_OT_API.HIGHLIGHT_TABLE);
PROCEDURE get_highlight (
session_id IN NUMBER,
bodypart_obj IN MAIL_BODYPART_OBJ,
flags IN INTEGER,
text_query IN VARCHAR2,
incl_binary_parts IN BOOLEAN,
highlight_buffer OUT ES_OT_API.HIGHLIGHT_TABLE);
Parameters
Table 1-87 GET_HIGHLIGHT Parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The message object |
|
|
The body-part object |
|
|
The returned buffer format Values are:
|
|
|
The string you want to query |
|
|
If false, the non-text part is ignored |
|
|
The highlight buffer |
This procedure retrieves the mark-up text for the message or body-part. If a message object is specified, the entire message is processed. If a body-part object is specified, the part must be a simple type and not contain any other body-parts.
Throws Exceptions
mail_errors.unauthenticated_err
mail_errors.sql_err
mail_erros.imt_err
mail_errors.bad_message_var
mail_errors.bad_msgpart_var
mail_errors.no_markup
mail_errors.no_binary_err
Syntax
PROCEDURE get_markuptext (
session_id IN NUMBER,
message_obj IN MAIL_MESSAGE_OBJ,
flags IN INTEGER,
text_query IN VARCHAR2,
incl_binary_parts IN BOOLEAN,
tag_set IN VARCHAR2 DEFAULT 'TEXT_DEFUALT',
start_tag IN VARCHAR2 DEFAULT NULL,
end_tag IN VARCHAR2 DEFAULT NULL,
prev_tag IN VARCHAR2 DEFAULT NULL,
next_tag IN VARCHAR2 DEFAULT NULL,
buffer OUT CLOB);
PROCEDURE get_markuptext (
session_id IN NUMBER,
bodypart_obj IN MAIL_BODYPART_OBJ,
flags IN INTEGER,
text_query IN VARCHAR2,
incl_binary_parts IN BOOLEAN,
tag_set IN VARCHAR2 DEFAULT 'TEXT_DEFUALT',
start_tag IN VARCHAR2 DEFAULT NULL,
end_tag IN VARCHAR2 DEFAULT NULL,
prev_tag IN VARCHAR2 DEFAULT NULL,
next_tag IN VARCHAR2 DEFAULT NULL,
buffer OUT CLOB);
Parameters
Table 1-88 GET_MARKUPTEXT Parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The message object |
|
|
The body-part object |
|
|
The returned buffer format. Values are:
|
|
|
The string you want to query |
|
|
If false, non-text part is ignored |
|
|
Refer to Oracle Text documentation |
|
|
Refer to Oracle Text documentation |
|
|
Refer to Oracle Text documentation |
|
|
Refer to Oracle Text documentation |
|
|
Refer to Oracle Text documentation |
|
|
The mark-up text buffer |
This procedure retrieves the filtered text for the message or body-part. If a message object is specified, the entire message is processed. If a body-part object is specified, the part must be a simple type and not contain any other body-parts.
Throws Exceptions
mail_errors.unauthenticated_err
mail_errors.sql_err
mail_errors.imt_err
mail_errors.bad_message_var
mail_errors.bad_msgpart_var
mail_errors.no_binary_err
Syntax
PROCEDURE get_filtered_text (
session_id IN NUMBER,
message_obj IN MAIL_MESSAGE_OBJ,
flags IN INTEGER,
incl_binary_parts IN BOOLEAN,
buffer OUT CLOB);
PROCEDURE get_filtered_text (
session_id IN NUMBER,
bodypart_obj IN MAIL_BODYPART_OBJ,
flags IN INTEGER,
incl_binary_parts IN BOOLEAN,
buffer OUT CLOB);
Parameters
Table 1-89 GET_FILTERED_TEXT Parameters
| Parameter | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The message object |
|
|
The body-part object |
|
|
The returned buffer format Values are:
|
|
|
If false, the non-text part is ignored |
|
|
The filtered text buffer |
This procedure retrieves the tokens for the message or body-part. If a message object is specified, the entire message is processed. If a body-part object is specified, the part must be a simple type and not contain any other body-parts.
Throws Exceptions
mail_errors.unauthenticated_err
mail_errors.sql_err
mail_errors.imt_err
mail_errors.bad_message_var
mail_errors.bad_msgpart_var
mail_errors.no_binary_err
Syntax
PROCEDURE get_tokens (
session_id IN NUMBER,
message_obj IN MAIL_MESSAGE_OBJ,
language IN VARCHAR2,
incl_binary_parts IN BOOLEAN,
token_buffer OUT ES_OT_API.TOKEN_TABLE);
PROCEDURE get_tokens (
session_id IN NUMBER,
bodypart_obj IN MAIL_BODYPART_OBJ,
language IN VARCHAR2,
incl_binary_parts IN BOOLEAN,
token_buffer OUT ES_OT_API.TOKEN_TABLE);
Parameters
Table 1-90 GET_TOKENS Parameters
| Parameters | Description |
|---|---|
|
|
An identifier that represents a user's authenticated session |
|
|
The message object |
|
|
The body-part object |
|
|
The language of the message or body-part data. |
|
|
If false, the non-text part is ignored |
|
|
The token buffer |
external_rule_err EXCEPTION
Error No: 20001
Message: Error executing external rule
Cause: A rule defined as an external PL/SQL procedure failed during execution
Action: Check the correctness of the external PL/SQL procedure
external_cond_err EXCEPTION
Error No: 20002
Message: External condition failed
Cause: A condition defined as an external PL/SQL function failed during evaluation
Action: Check the correctness of the external PL/SQL function
too_many_rules EXCEPTION
Error No: 20003
Message: Too many rules fired, stop
Cause: Number of rules triggered for a message exceeded the maximum number of rules allowed. The default is 20
Action: Check if the rules involved causes infinite looping. Reduce the number of rules defined. Ask the administrator to increase the maximum number of rules allowed.
sql_err EXCEPTION
Error No: 20101
Message: Some SQL error occured: %s
Cause: An SQL error occured. See the error text returned for more information
Action: Refer to the Oracle9i Database Error Messages guide
imt_err EXCEPTION
Error No: 20102
Message: interMedia Text error: %s
Cause: Internal Oracle Text error occured. See the error text returned for more information
Action: Refer to the Oracle Text documentation
bad_message_var EXCEPTION
Error No: 20103
Message: No such message: %s
Cause: Exception is raised when the message or body-part object passed in is invalid. The message may have been removed by another mail session
Action: Ensure that the message or body-part object passed in is valid
bad_msgpart_var EXCEPTION
Error No: 20104
Message: No such message part: %s
Cause: Exception is raised when the MIME-level of the message or body-part object passed in is invalid
Action: Ensure that the MIME level of the message or body-part object passed in is valid
no_binary_err EXCEPTION
Error No: 20106
Message: No binary part: %s
Cause: Exception is raised when the specified message part is binary, but the API option specifies that binary is false
Action: Set the withbinary parameter to True for Oracle Text
unauthenticated_err EXCEPTION
Error No: 20201
Message: User needs to be authenticated first
Cause: User is not currently authenticated
Action: Call the mail_session.login() procedure to authenticate the user
folder_closed_err EXCEPTION
Error No: 20202
Message: Folder needs to be opened first!
Cause: Certain operations require that the folder involved be opened first
Action: Call the mail_folder.open_folder() procedure to open the folder first
msg_compose_limit_err EXCEPTION
Error No: 20203
Message: Compose one message at a time!
Cause: Exception is raised if user tries to compose more than one message at a time
Action: Send or append the current message before starting to compose the second message
folder_not_found_err EXCEPTION
Error No: 20204
Message: Folder does not exist: %s
Cause: Exception is raised if user is trying to do an operation on a folder that does not exist on the mail store
Action: Ensure that the folder exists before performing the operation
folder_already_exists_err EXCEPTION
Error No: 20205
Message: Folder already exists: %s
Cause: Exception is raised if user tries to create or rename as a folder name that already exists
Action: Choose a different folder name and retry
operation_not_allowed EXCEPTION
Error No: 20206
Message: Operation not allowed: %s
Cause: Possible causes for this exception are:
Trying to delete the INBOX folder
Trying to rename a folder to a descendent older name, such as x/y
Action: Do not try to re-arrange a folder hierarchy with the rename operation. Use the create and delete operations to achieve the desired folder hierarchy
param_parse_err EXCEPTION
Error No: 20208
Message: Param parsing error: %s
Cause: Errors in the parameter passed into the API. Possible causes are:
The specified message UID does not exist in the current folder
Trying to send or append a message not currently in composition
Passed in message or bodypart object with wrong Content-Type value
Invalid sort criteria
Unmatched parentheses or quote in search string
Unsupported search criteria
Trying to create a folder with null foldername
Unknown search criteria
The header value exceeds the 2000 length limit
Action: Correct the parameter passed to the API and try again
internal_err EXCEPTION
Error No: 20209
Message: Internal error: %s
Cause: An internal assertion has failed. Data is in an inconsistent state
Action: Contact Oracle Support
folder_name_err EXCEPTION
Error No: 20210
Message: Bad folder name: %s
Cause: Trying to create or rename a folder under another user's name space
Action: Correct the folder name and try again
login_err EXCEPTION
Error No: 20211
Message: Oracle Internet Directory Login Error: %s
Cause: Exception is raised when an invalid username or password is specified
Action: Check the spelling and try again
folder_type_err EXCEPTION
Error No: 20212
Message: Folder type voilation: %s
Cause: Possible causes for this error include:
Trying to open a non-selectable folder
Trying to create a folder where the parent folder does not permit sub-folder creation
Trying to delete a non-selectable folder that still has sub-folders
Trying to copy messages to a non-selectable folder
Action: Avoid these types of folder violations
smime_err EXCEPTION
Error No: 20213
Message: S/MIME error: %s
Cause: Some error in calling S/MIME functions. The S/MIME error code reveals more details.
Action: Refer to the S/MIME documentation for the error code descriptions
