mailResolveRecipient PowerScript function
Description
Obtains a valid e-mail address based on a partial or full
user name and optionally updates information in the system’s
address list if the user has privileges to do so.
Controls
mailSession object
Syntax
|
1 |
<span>mailsession</span>.<span>mailResolveRecipient</span> ( <span>recipient </span>{, <span>allowupdates</span> } ) |
|
Argument |
Description |
|---|---|
|
mailsession |
A mailSession object identifying the |
|
recipient |
A mailRecipient structure or a string |
|
allowupdates (optional) |
A boolean indicating whether updates |
Return Values
mailReturnCode. Returns one of the following values:
-
mailReturnSuccess!
-
mailReturnFailure!
-
mailReturnInsufficientMemory!
-
mailReturnUserAbort!
If any argument’s value is null, mailResolveRecipient returns null.
Usage
Use mailResolveRecipient to verify that
a name is a valid address in the mail system. The function reports
mailReturnFailure! if the name is not found.
If you supply a mailRecipient structure, mailResolveRecipient fills
the structure with valid address information when it resolves the
address. If you supply a name as a string, mailResolveRecipient replaces
the string’s value with the full user name as recognized
by the mail system. An address specified as a string is adequate
for users in the local mail system. If you are sending mail through gateways
to other systems, you should obtain full address details in a mailRecipient
structure.
If more than one address on the mail system matches the partial
address information you supply to mailResolveRecipient,
the mail system may display a dialog box allowing the user to choose
the desired name.
If you supply a mailRecipient structure that already has address
information, mailResolveRecipient corrects the
information if it differs from the mail system. If you set allowupdates to true and
the information differs from the mail system, mailResolveRecipient corrects
the mail system’s information if the
user has rights to do so. Be careful that the address information
you have is correct when you allow updating.
Before calling mail functions, you must declare and create
a mailSession object and call mailLogon to establish
a mail session.
Examples
This example checks whether there is a user J Smith
is on the mail system. If there is a user whose name matches, such
as Jane Smith or Jerry Smith, the variable mname is
set to the full name. If both names are on the system, the mail system
displays a dialog box from which the user chooses a name. Mname is set
to the user’s choice. The application has already created
the mailSession object mSes and logged on:
|
1 |
mailReturnCode mRet |
|
1 |
string mname |
|
1 |
mname = "Smith, J" |
|
1 |
mRet = mSes.<span>mailResolveRecipient</span>(mname) |
|
1 |
IF mRet = mailReturnSuccess! THEN |
|
1 |
MessageBox("Address", mname + " found.") |
|
1 |
ELSEIF mRet = mailReturnFailure! THEN |
|
1 |
MessageBox("Address", "J Smith not found.") |
|
1 |
ELSE |
|
1 |
MessageBox("Address", "Request not evaluated.") |
|
1 |
END IF |
In this example, sle_to contains
the full or partial name of a mail recipient. This example assigns
the name to a mailRecipient object and calls mailResolveRecipient
to find the name and get address details. If the name is found,
mailRecipientDetails displays the information and the full name
is assigned to sle_to. The application
has already created the mailSession object mSes and
logged on:
|
1 |
mailReturnCode mRet |
|
1 |
mailRecipient mRecip |
|
1 |
|
1 |
mRecip.Name = sle_to.Text |
|
1 |
mRet = mSes.<span>mailResolveRecipient</span>(mRecip) |
|
1 |
IF mRet <> mailReturnSuccess! THEN |
|
1 |
MessageBox ("Address", & |
|
1 |
sle_to.Text + "not found.") |
|
1 |
ELSE |
|
1 |
mRet = mSes.mailRecipientDetails(mRecipient) |
|
1 |
sle_to.Text = mRecipient.Name |
|
1 |
END IF |