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.
mailSession object
mailsession.mailResolveRecipient ( recipient {, allowupdates } )
Argument |
Description |
|---|---|
mailsession |
A mailSession object identifying the session in which you want to resolve the recipient. |
recipient |
A mailRecipient structure or a string variable whose value is a recipient’s name. The recipient’s name is a property of the mailRecipient structure. MailResolveRecipient sets the value of the string to the recipient’s full name or the structure to the resolved address information. |
allowupdates (optional) |
A boolean indicating whether updates to the recipient’s name will be allowed. If the user does not have update privileges for the mail system, then allowupdates is ignored. The default is false. |
mailReturnCode. Returns one of the following values:
mailReturnSuccess!
mailReturnFailure!
mailReturnInsufficientMemory!
mailReturnUserAbort!
If any argument’s value is null, mailResolveRecipient returns null.
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.
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:
mailReturnCode mRet
string mname
mname = "Smith, J"
mRet = mSes.mailResolveRecipient(mname)
IF mRet = mailReturnSuccess! THEN
MessageBox("Address", mname + " found.")
ELSEIF mRet = mailReturnFailure! THEN
MessageBox("Address", "J Smith not found.")
ELSE
MessageBox("Address", "Request not evaluated.")
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:
mailReturnCode mRet
mailRecipient mRecip
mRecip.Name = sle_to.Text
mRet = mSes.mailResolveRecipient(mRecip)
IF mRet <> mailReturnSuccess! THEN
MessageBox ("Address", &
sle_to.Text + "not found.")
ELSE
mRet = mSes.mailRecipientDetails(mRecipient)
sle_to.Text = mRecipient.Name
END IF
