class ref name: email_address
category-group: email
layer: 9
header file: z_emailaddr.h
libraries: libz00.lib libz01.lib libz02.lib libz03.lib libz04.lib libz05.lib libz06.lib libz07.lib libz08.lib libz09.lib

synopsis.
The email_address class (" email_address_o ") is the Swiss army knife of sending e-mail messages in the Z Directory. An email_address_o instance represents a single e-mail message. The class has a large set of member functions, representing all the various things one can do with an e-mail: setting the MTA, port number, MIME type, 'From:', 'Reply To:', and subject fields; setting the recipient; adding or deleting attachments, etc.

description.
To send mail with the email_address_o class, use the member function send_message() or send_files() . The latter is for messages with file attachments. The implementation for sending mail in Microsoft environments is via COM (and CDO), and in unix environments, it is done simply via a system() call to the host computers's mail program. You must have a functional mail server (an MTA ) in order to have this object successfully do something. If you don't need to actually send e-mail, say, for modeling, testing, or whatever pedagogical purposes, then you can use this class to simply set and get values.

This class inherits from the address object ( address_o ). The class inheritance hierarchy is fairly deep:

email_address_o
  address_o
    orthodox_o
      dbtable_o
        rec_dbag_o
          list_dbag_o
            dbag_o

That is, the "grandparent" class is the orthodox object, and the most remote ancestor is the basic data-bag class object. As an orthodox sub-class, this class is required to have a database schema. The 'columns' section of this schema looks like this:

  columns \
  [
    <name       type qual nulls_ok is_uniq >
    <account    char      40   YES   NO    >
    <hostdomain char      50   YES   NO    >
    <free_text  char      60   YES   NO    >
    <options    char       5   YES   NO    >
    <note       char      40   YES   NO    >
    <location   char      30   YES   NO    >
    <octet0     smallint \"\"  YES   NO    >
    <octet1     smallint \"\"  YES   NO    >
    <octet2     smallint \"\"  YES   NO    >
    <octet3     smallint \"\"  YES   NO    >
  ]

(The columns "default", "check", "ref_table" and "ref_column" columns all have empty values, and have been omitted for brevity). The "octet" fields are currently unused and might get deleted in the future. They are intended to represent the IP address values of the underlying host computer the e-mail address belongs to.

More info than just strictly an address can be maintained by the e-mail address object. You can assign certain "flags" to an e-mail that this class will record:

    B - "bad"; the e-mail address is "bad". Typically this
        would mean that it cannot be reached, has been removed,
        or in some way is no longer of service.
    O - "old"; the e-mail address used to belong to somebody
        (or something) but is now defunct. This is a specialization
        of the "bad" case - it is bad, because it is old.
    A - "avoid"; meaning, avoid sending e-mail to the recipient.
        This is probably due to hostility. For example, suppose
        you have this set of e-mail addresses: tjfan@watson.ibm.com,
        dhj@ibm.com, griefer@almaden.ibm.com, dgillum@ibm.net,
        clark@watson.ibm.com, and caswell@watson.ibm.com. You want
        to send them all your newsletter. However, the addresses
        "griefer" and "dgillum" are no longer valid (the persons are
        probably no longer working for IBM) and you don't want to send
        anything to the last one because he threatened you with
        violence. So you would mark these address as 'bad' and 'avoid',
        like so:
            griefer@almaden.ibm.com {bad}
            dgillum@ibm.net {bad} {note: at Hawthorne now}
            caswell@watson.ibm.com {avoid}
    ? - "odd". the meaning of this has been lost to us. We are guessing
        that its purpose was to denote that the given address may be
        incorrect, eg, the person who provided the address is unsure
        of its correctness (or perhaps it is a guess, based on corporate
        assignment conventions).

Note that these "reserved words" ('bad', 'old', 'avoid') map onto a single letter. The 1-letter syntax is used only in the case of the "options" values in a databag, when mapping a databag to an e-mail address object. In that case, multiple properties can be assigned by simply concatenating the letters:

    options "OA"

In this case, the properties are "old" and "avoid" (not a good example; you wouldn't have to avoid it if it's old-obsolete). In the case of assigning a string to an e-mail address object, you would put tack on property reserved words to the end of the e-mail address, enclosed by curly-braces, and some whitespace to separate them (at least 1 blank). In addition to the properties, you can attach a short note to an e-mail address, as you can see in the above example. The syntax for this is {note: [TEXT]}, where "[TEXT]" is your note-text (the '[' & ']' square brackets are not part of the syntax, ignore them). These lexemes (properties and note) can appear in any order and are optional.

Assignment of properties (turning them on or off) can be done 3 ways:

1. assignment via a string:

       email_address_o x;
       x = "myaccount@hotmail.com {note: nothing} {avoid}";
   

2. assignment by copying from another e-mail object:

       email_address_o x, y;
       y = "myaccount@hotmail.com {note: nothing} {avoid}";
       x = y;              // x inherits the note and the 'avoid' property
   

3. By explicit member function call:

       email_address_o x;
       x.set_note("nothing");
       x.set_avoid();
   

These are admittedly, application- and domain- specific protocols we have assigned to e-mail. These particular properties have proven useful during the history and evolution of Vettrasoft's consulting work. Ideally, you should be able to assign your own properties to an address - this idea is still evolving and is currently not implemented.

member functions (primary)

email_address_o()
SIGNATURE: email_address_o ()
SYNOPSIS:
creates a a new, 'empty' email_address object. It has no address. Its properties are set to these default values:

mime type = "text/plain"
charset = iso-8859-1
encoding = 8 bit
port = 25

 

email_address_o(email_address_o)
SIGNATURE: email_address_o (const email_address_o &that)
SYNOPSIS:
creates a a new email_address object; an exact image of the copied email_address object "that". This includes its properties (mime type, character set, avoid/ignore/is-bad flags), the server it is to connect to, server port number, etc.
 

destructor
SIGNATURE: ~email_address_o ()
SYNOPSIS:
virtual destructor. The email address instance is 'wiped out'. Its address is reset to empty, including "free text" string, and all properties are set to "empty" values.
 

operator = (email_address_o)
SIGNATURE: const email_address_o &operator = (const email_address_o &rhs)
SYNOPSIS:
copies exactly the RHS [Right Hand Side] object "rhs". the resultant email_address instance is the same as if the copy constructor was used with "rhs" as its argument.
RETURNS: a reference to the current object.
 

email_address_o(<args>)
SIGNATURE: email_address_o (const string_o &s)
SYNOPSIS:
This constructor creates a new email_address object. It sets the email_address's address to the value given by input variable 's'. If the e-mail address in 's' is invalid, the object will have an uninitialized address, exactly as if the default constructor was invoked.
 

operator = (email_address_o)
SIGNATURE: const email_address_o &operator = (const string_o &s)
SYNOPSIS:
copy the settings of string object 's' into the current object. If 's' is a valid e-mail address, the current object's address will be set to that of 's'. This will update 3 internal components: "account" part, "host domain" part, and "free text" part. If 's' does not represent a valid e-mail address, the operation will fail. Note that there is no way to indicate success or failure (due to the nature of the member function signature).
RETURNS: a reference to the current object.
 

operator = (email_address_o)
SIGNATURE: orthodox_o &operator = (const rec_dbag_o &source_bag)
SYNOPSIS:
This assignment operator sets (or resets) the address of the object to values found in the recursive data-bag 'source_bag'. This data-bag should have a structure similar to this:

"REC_BAG
(
    account \"arthur.g.randol\"
    hostdomain "exxonmobil.com"
    free_text \"arthur.g.randol@exxonmobil.com\"
    options \"BOAI?\"
)

Calling this assignment operator - member function will set each of the corresponding values in the email address object as those listed in the data-bag [above]. The "options" values, if provided, will set the corresponding option in the e-mail address object, based on this mapping:

    B - set_bad()
    O - set_old()
    A - set_avoid()
    ? - set_ignore()

See the discussion on adding properties to an address (on this page) for more info.
RETURNS: a reference to the current object (as type orthodox_o - a parent class)
 

operator ==()
SIGNATURE: int operator == (const email_address_o &rhs) const
SYNOPSIS:
compare two email address objects for equality. This member function tests for equality of the account and domain name components of the e-mail addresses. If the domain is the same, it looks at the account name. The inspection of both items is case-insensitive (eg, caps doesn't matter). The addresses of both the objects (the current object and the Right-Hand-Side object) must be set, or the results are unpredictable.
RETURNS:
1: the addresses are equivalent
0: the addresses are different
 

operator !=()
SIGNATURE: int operator != (const email_address_o &rhs) const
SYNOPSIS:
compare s the current object with the object "rhs" (the Right-Hand-Side object) for inequality. If they are different, this "operator" member function returns 1. This function is the converse of the "== operator". See

int operator == (const email_address_o &rhs)

for more informaiton.
RETURNS:
1: the addresses are different
0: the addresses are equivalent
 

[string_o conversion operator]()
SIGNATURE: operator string_o () const
SYNOPSIS:
converts an e-mail address to a string. Example usage:

string_o s;
email_address_o x ("abc@yahoo.com");
s = x;                  // now 's' contains"abc@yahoo.com"
s = x.print();          // alternative syntax

 

is_set()
SIGNATURE: boolean is_set () const
SYNOPSIS:
tells if the object's addfress has been [successfully] set. setting an address is done via the "set_recipient()" member function.
RETURNS:
TRUE: the address is set
FALSE: the address has not been set
 

is_ok()
SIGNATURE: boolean is_ok () const
SYNOPSIS:
the converse of "is_bad()". Note that this is not the usual meaning of whether an object is "ok" - if the application has marked the e-mail address as "bad", it is bad; otherwise, it is ok.
 

account()
SIGNATURE: const string_o &account () const
SYNOPSIS:
returns the "account" part of an e-mail address. Given this address:
basepart@mydomain.com
This member function would return "basepart". This function is the complement of "domain()", which in this case would return "mydomain.com" (as a string object).
RETURNS: string object, containing the "account" part of an e-mail address. If the address is not set, an empty string ("") is returned.
 

domain()
SIGNATURE: const string_o &domain () const
SYNOPSIS:
returns the "domain" part of an e-mail address. Given this address:
basepart@mydomain.com
This member function would return "mydomain.com". This function is the complement of "account()" (see which).
RETURNS: string object, containing the "host domain" part of an e-mail address. If the address is not set, an empty string ("") is returned.
 

subject()
SIGNATURE: const string_o &subject () const
SYNOPSIS:
returns the e-mail subject line. If no subject has been set (via member function set_subject()), the string returned is empty ("").
 

mime_type()
SIGNATURE: const string_o &mime_type () const
SYNOPSIS:
returns the mime type, as a string. If no mime type has been set (which is done via "set_mimetype()"), the contents of the returned string is empty. Note that the mime type string is not transformed in any way, and is simply passed thru to the implementation. The most common values are "text/html" and "text/plain".
This is also known as Content-type .
RETURNS: returns a string containing the value of this e-mail property. if not set, the contents of the string will be empty ("").
 

port()
SIGNATURE: int port () const
SYNOPSIS:
returns the mail server (Mail Transport Agent, or MTA) port number for the current e-mail address object. Note that if "not set", this returns -1, but by default, the port number is set to 25 (the default STMP port number).
RETURNS: the MTA port number
 

charset()
SIGNATURE: const string_o &charset () const
SYNOPSIS:
Returns a string containing the character encoding for emails in the current email_address_o object. This is also known as "character set", "character map", and "code page". Typical values include "UTF-8" (unicode), "ISO-8859-1" (Latin), or "Windows-1252".
RETURNS: returns a string containing the value of this e-mail property. if not set, the contents of the string will be empty ("").
 

encoding()
SIGNATURE: const string_o &encoding () const
SYNOPSIS:
returns the e-mail "encoding" value (as set via the "set_encoding()" member function call). A typical value is "8bit".
RETURNS: returns a string containing the value of this e-mail property. if not set, the contents of the string will be empty ("").
 

reply_to()
SIGNATURE: const string_o &reply_to () const
SYNOPSIS: returns the value for the 'reply To:' field of an e-mail. Use "set_replyto()" to set this value.
RETURNS: returns a string containing the value of this e-mail property. if not set, the contents of the string will be empty ("").
 

show_options()
SIGNATURE: boolean show_options () const
SYNOPSIS:
Tells if the object is in "show options" mode. See the "options()" and "set_showopts()" member functions for more information about email address options (also the general description section on this page).
 

is_bad()
SIGNATURE: boolean is_bad () const
SYNOPSIS: returns TRUE if the e-mail address has been marked "BAD" (by the application), and FALSE otherwise.
RETURNS:
TRUE: the e-mail address has been designated "bad" (either via an explicit call to "set_bad()" member function, by copying/assignment of another e-mail object, or by assignment via a string
FALSE: the e-mail address has been designated "bad"
 

is_old()
SIGNATURE: boolean is_old () const
SYNOPSIS: This function can be used to explicitly set the "is old" property of the e-mail address.
RETURNS:
TRUE: the e-mail address has been designated "old"
FALSE: the e-mail address has not been designated "old".
 

is_avoid_on()
SIGNATURE: boolean is_avoid_on () const
SYNOPSIS: tells if the e-mail address "avoid" property has been set or not. If so, the address should not be used!
RETURNS:
TRUE: the e-mail address has been designated "to be avoided"
FALSE: the e-mail address is not designated "to be avoided" (normal case).
 

is_ignore_on()
SIGNATURE: boolean is_ignore_on () const
SYNOPSIS:
tells if the e-mail address "ignore" property has been set or not. If so, the address should be skipped if encountered in a bulk mailing. This attribute is similar to "avoid" (but without the extremely negative connotation).
RETURNS:
TRUE: the e-mail address has been designated "ignore"
FALSE: the e-mail address has not been designated "ignore".
 

options()
SIGNATURE: string_o options () const
SYNOPSIS:
this member function creates a string of all the set "options" of the e-mail address object. It will do so only if this objects is in the "show options" mode. To set this mode, call the member function set_showopts() . To turn it off, call it with an input parameter argument of FALSE:

email_address_o x;
x.set_options("{bad} {avoid}");
x.set_showopts(FALSE);          // <-- "show opts" turned off
string_o s = x.options();       // <-- returns empty string
x.set_showopts();               // <-- now it's turned on
s = x.options();                // now s = "{bad} {avoid}"

This function is used by the member function print(), which is in turn used by the string_o "cast" operator. Hence, any e-mail address to string conversion uses this function to determine whether or not to add the properties.
 

freetext()
SIGNATURE: const string_o &freetext (int *pi = NULL) const
SYNOPSIS:
this returns the e-mail address as a string, but instead of assembling it from the [parsed] account and host-domain components, it simply returns the raw string that you provided the object (assuming you did so in the first place). If there is no such field (eg, the address has not been set), the output parameter is set to 1 and an empty string is returned.
PARAMETERS

pi: error indicator variable. The values this output parameter takes on is either 0 or 1:
0: the "free text" field was found, and the value successfully returned;
1: no "free text" field found

 

location()
SIGNATURE: const string_o location (int *pi = NULL) const
SYNOPSIS:
This returns a string that describes the "location" of the e-mail address. The location property can be set with the member function set_location(). This member function is provided as part of the standard set of functions for address objects. In this case, specifying a "location" for an e-mail address is the least sensible (for the case of a postal address or a telephone number, this would have much more sensible semantic meaning). However, since an e-mail addresses generally has an owner, the interpretation of location in this case is where the owner (usually a person) is typically to be found for this e-mail address. The Vettrasoft convention is to specify a city in the body text of this value.

Consider a person John Smith, with 2 e-mail addresses:
johnsmith@hotmail.com
jsmith@sysadmin.bigbiz.com
John lives in Newark, NJ (USA) and works in Manhattan - that is, New York, NY (USA). The first e-mail address in this example is his personal account, which we will say 'habitats' at his home where he lives, and the latter is found at his work place. We would set the locations thusly:

  email_address_o js_home = "johnsmith@hotmail.com";
  email_address_o js_work = "jsmith@sysadmin.bigbiz.com";
  js_home.set_location("Newark");
  js_work.set_location("New York");

Or, we can do the assignment directly in the strings:

  email_address_o jsh = "johnsmith@hotmail.com {loc: Newark}";
  email_address_o jsw = "jsmith@sysadmin.bigbiz.com {loc: New York}";

PARAMETERS

pi: error indicator variable. The values this output parameter takes on is either 0 or 1:
0: the field was found, and the value successfully returned;
1: no such field found

 

note()
SIGNATURE: const string_o note (int *pi = NULL) const
SYNOPSIS:
returns any "note" attached to the e-mail address object. Notes cannot span multiple lines. They are intended to be quite short, generally under 40 characters.
PARAMETERS

pi: error indicator variable. The values this output parameter takes on is either 0 or 1:
0: the field was found, and the value successfully returned;
1: no such field found

 

from()
SIGNATURE: const string_o &from () const
SYNOPSIS:
returns the e-mail "From:" field, if set. Setting this field is done via the set_from() member function call. It is usually required when sending e-mail (it depends on the MTA, actually).
 

mta()
SIGNATURE: const string_o &mta () const
SYNOPSIS: returns a string containing the text describing the Mail Transport Agent assigned to the object (if done).
RETURNS: [string_o] the value of the MTA field, if set. If not set, the string is empty ("").
 

mta_acct()
SIGNATURE: const string_o &mta_acct () const
SYNOPSIS: returns a string containing account (eg, user name) for the MTA (if set).
RETURNS: [string_o] the value of the MTA account field, if set. If not set, the string is empty ("").
 

mta_pass()
SIGNATURE: const string_o &mta_pass () const
SYNOPSIS: returns a string containing the password for the MTA (if set).
RETURNS: [string_o] the value of the MTA password field, if set. If not set, the string is empty ("").
 

set_to()
SIGNATURE: int set_to (const string_o &s, int *pi = NULL)
SYNOPSIS:
this is an "alias" for the set_recipient() member function. That is, this function is simply another name provided for setting the "To:" e-mail field. It is an inline function that calls set_recipient() .
 

set_account()
SIGNATURE: int set_account (const string_o &newacct)
SYNOPSIS:
sets the "account" part of an e-mail address to the contents of input parameter 'newacct'. The contents of 'newacct' can be anything.
RETURNS: 0
 

set_hostdomain()
SIGNATURE: int set_hostdomain (const string_o &newdom)
SYNOPSIS: sets the "domain" part of an e-mail address to the contents of input parameter 'newdom'.
RETURNS: 0
 

set_freetext()
SIGNATURE: int set_freetext (const string_o &newfree)
SYNOPSIS:
sets the of an "freetext" compohnent of an e-mail address to the contents of input parameter 'newfree'. The state of the object is set to 'is set' (this allows sending mail to the specified address).
 

set_subject()
SIGNATURE: int set_subject (const string_o &s)
SYNOPSIS: sets the subject line to 's' This .
PARAMETERS

s: string object containing the text of en email "subject" line. This text cannot be more than 1 line. An empty string can be supplied; this will result in an e-mail message with no subject line.

RETURNS:
0: subject successfully set
-1: too many lines (2+) in the input variable
 

set_note()
SIGNATURE: int set_note (const string_o &s)
SYNOPSIS:
Attach a note to the e-mail address object. This function provides standard functionality in address objects, especially the postal address object. A note is intended to be small: it must be on one line, should be short enough so that the full e-mail address, with all properties and note, fits within an 80-character width terminal (eg, the length should not exceed about 25 characters).
RETURNS:
0: subject successfully set
-1: too many lines (2+) in the input variable
 

set_location()
SIGNATURE: int set_location (const string_o &s)
SYNOPSIS:
Attach a location designator to the e-mail address object. This function provides standard functionality in address objects, especially the postal address object. The text for a "location" is intended to be small: it must be on one line, should be short enough so that the full e-mail address, with all properties and note, fits within an 80-character width terminal (eg, the length should not exceed about 25 characters).
By Vettrasoft convention, the location is simply a city name. If there are multiple locations within the same city, the city name is followed by a slash, then the street address. Some examples:
servicedesk@firstnlc.net {loc: Anaheim}
itnet.toronto@itnet.ca {loc: Toronto / 121 Bloor Street East}

RETURNS:
0: subject successfully set
-1: too many lines (2+) in the input variable
 

set_mimetype()
SIGNATURE: int set_mimetype (const string_o &new_mime)
SYNOPSIS:
Set the e-mail message MIME type to the text given in input variable 'new_mime'. The value of the string is passed raw (no modifications are done) to the e-mail transport implementation during a send_message() or send_files() operation. See member function mime_type() for more info about MIME types.
 

set_encoding()
SIGNATURE: int set_encoding (const string_o &new_enc)
SYNOPSIS:
sets the "encoding" property of an e-mail message. In e-mail headers, this is usually denoted "Content-Transfer-Encoding" and a very typical value is "8bit". Other values for the 'new_enc string include "7bit" and "binary".
This function passes the value in 'new_enc' directly to the e-mail transport system during a send_message() call.
A good overview of this field can be found here:
http://en.wikipedia.org/wiki/MIME#Content-Transfer-Encoding
 

set_port()
SIGNATURE: int set_port (int new_portno)
SYNOPSIS: Set the e-mail (outbound/SMTP) server port number. The default value is 25. You can use any value here.
RETURNS: 0 (always)
 

set_charset()
SIGNATURE: int set_charset (const string_o &new_charset)
SYNOPSIS:
Set the "character set" property of the e-mail message to the contents of the string in input variable 'new_charset'. This function does no checking for the correctness of this variable. See member function charset() for more info on the semantics of this item.
RETURNS: 0 (always)
 

set_replyto()
SIGNATURE: int set_replyto (const string_o &srepto)
SYNOPSIS:
Set the "Reply To:" field of an e-mail message to the contents of input variable 'srepto'. This function does no checking for the correctness of the contents of this string. The value of the "Reply To:" field after a message is e-mailed is exactly whatever is in the string. By convention, this is oftn a name, in quotes, followed by an e-mail address, in angle-brackets. The text in quotes is often a name but can be anything. Here is an example:
Reply To: "Vettrasoft Engineering" The corresponding c++ code in this case would look like so:

  email_address_o x;
  x.set_from ("info@vettrasoft.com");
  x.set_replyto ("\Vettrasoft Engineering"\" ");

 

set_showopts()
SIGNATURE: int set_showopts (boolean onoff = TRUE)
SYNOPSIS:
this turns on (or off, if 'onoff' is set to TRUE) the "show options" mode. If this mode is off, any printing of the e-mail address will exclude a trailing "options" string. If on, all string representations of the address will have an option set appended to the address. See the "options()" member function for more info. Option strings are also described in the general description section on this page.
RETURNS:
TRUE: the e-mail address object is in "show options" mode; the "print()" function will return just the e-mail address (if set).
FALSE: the e-mail address object is not in the "show options" mode. Calling "print()" will result in a string containing the e-mail address (if set) only, without any option properties after the address.
 

set_recipient()
SIGNATURE: int set_recipient (const string_o &s, int *pi = NULL)
SYNOPSIS:
This function sets the "To:" e-mail field to the value given in 's'. The input parameter 's' must be a valid e-mail address. On unix systems, this can be just an account name. In this case, the account must be a valid account on the current host computer. If there is an error in calling this function, the parameter 'pi' is set to a non-zero value.

the input string 's' can also have options appended to it.
PARAMETERS

• pi: error indicator variable. The values this output parameter is as follows:
  0: ok; the recipient was successfully set
  1: bad e-mail syntax ('s' incorrect)
  2: couldn't get the current host computer name (this is a panic situation indicating that z_hostname() failed; this should never occur).
  3: the current object set to not assume curr host, and input e-mail address had no '@'
  4: illegal option(s) passed in
  5: bad internet/domain name given
• s: [input] string object, containing the e-mail address of the recipient. This string can also have optional properties at the end of it, after the address part. If so, the properties will be set. For example:
  email_address_o x; x.set_recipient ("abc@yahoo.com {avoid}");

 

set_from()
SIGNATURE: int set_from (const string_o &s)
SYNOPSIS: Sets the 'From:' field to that of 's'. This is important when communicating with an SMTP MTA.
TRAITS: this function should probably have an additional parameter ("int *") for indicating if any error(s) ocurred.
 

set_mta()
SIGNATURE: int set_mta (const string_o &new_mta)
SYNOPSIS:
Set the name of the mail server this object is to connect to. The name here is exactly the same was would be used for outgoing mail (SMTP server) in an e-mail client.
TRAITS: this function should probably have an additional parameter ("int *") for indicating if any error(s) ocurred.
 

set_mta_acct()
SIGNATURE: int set_mta_acct (const string_o &new_acct)
SYNOPSIS: Set the account ("user") name for the e-mail server. This is useful in the case where the MTA to connect to requires authentication.
TRAITS: this function should probably have an additional parameter ("int *") for indicating if any error(s) ocurred.
 

set_mta_pass()
SIGNATURE: int set_mta_pass (const string_o &new_pass)
SYNOPSIS:
Set the password for the e-mail server. This is useful in the case where the MTA to connect to requires authentication. This function should be thought of a one of a pair, the other being "set_mta_acct()".
TRAITS: this function should probably have an additional parameter ("int *") for indicating if any error(s) ocurred.
 

set_options()
SIGNATURE: int set_options (const string_o &so, int *pi)
SYNOPSIS:
this member function sets the options from the input variable 'so'. This function is analogous to that of the phone_number_o class. The properties can be turned on only via a string assignment. To turn one off, set the appropriate "xxx" function, like so:
set_xxx(FALSE);
PARAMETERS

• so: string object containing a list of properties to set for this object. In addition to propertiss, this string can contain a "location" and :"note" field. Each property (bad, old, avoid, ignore) must be enclosed in curly braces and separate by at least 1 blank character. The note and location field syntax is {keyword: TEXT}, where "keyword is one of ["loc", "note"]. Example:
  "{old} {avoid} {loc: Los Angeles}"
• pi: error indicator variable. The values this output parameter is as follows:
  0: all ok, parse-set was successful;
  1: 1st char not a "{"
  2: no match for "{ .. }" in given string
  3: no arguments, junk text, or other bad format
  4: corruption in regular expression parsing (!)
  5: illegal property keyword (non-":" case)
  6: syntax error in non-property field case. (expecting this syntax: "{: }")
  7: illegal keyword encountered in non-property field's phrase

 

set_bad()
SIGNATURE: int set_bad (const boolean x = TRUE)
SYNOPSIS:
sets the "bad" property on (if x is TRUE) or off (if x is FALSE). For more info about properties, see the discussion in the main description section on this page.
RETURNS:
0: the property modification succeeded
-1: the "options" buffer is full (more than 18 options). This should never happen
 

set_old()
SIGNATURE: int set_old (const boolean x = TRUE)
SYNOPSIS:
sets the "old" property on (if x is TRUE) or off (if x is FALSE). For more info about properties, see the discussion in the main description section on this page.
The "old" property indicates that the e-mail address is no longer functional since it has been disabled. It is a specialization of the "bad" property.
RETURNS:
0: the property modification succeeded
-1: the "options" buffer is full (more than 18 options). This should never happen.
 

set_odd()
SIGNATURE: int set_odd (const boolean x = TRUE)
SYNOPSIS:
sets the "odd" property on (if x is TRUE) or off (if x is FALSE). For more info about properties, see the discussion in the main description section on this page.
RETURNS:
0: the property modification succeeded
-1: the "options" buffer is full (more than 18 options). This should never happen.
 

set_avoid()
SIGNATURE: int set_avoid (const boolean x = TRUE)
SYNOPSIS:
sets the "old" property on (if x is TRUE) or off (if x is FALSE). For more info about properties, see the discussion in the main description section on this page.
The "avoid" property is an indicator to tell you not to mail anything to the given address.
RETURNS:
0: the property modification succeeded
-1: the "options" buffer is full (more than 18 options). This should never happen
 

set_ignore()
SIGNATURE: int set_ignore (const boolean x = TRUE)
SYNOPSIS:
sets the "ignore" property on (if x is TRUE) or off (if x is FALSE). For more info about properties, see the discussion in the main description section on this page.
RETURNS:
0: the property modification succeeded
-1: the "options" buffer is full (more than 18 options). This should never happen
 

reset()
SIGNATURE: int reset ()
SYNOPSIS:
resets the object to its at-default-construction state. Wipes out any address stored inside. Resets all properties to their default values.
 

print()
SIGNATURE: string_o print (boolean incl_opts = FALSE) const
SYNOPSIS:
prints the e-mail address to a string format. This function is a synonym (and an alternate) to the "string object cast" operator. In the example below, the value of the string object 's' is exactly the same after its assigment statements:

  string_o s;
  email_address_o x = "johnsmith@hotmail.com";
  s = x;
  s = x.print();

PARAMETERS

incl_opts: if TRUE, prints any "options" assigned to the e-mail address. This is a Vettrasoft protocol. by default, this is FALSE.

 

clone()
SIGNATURE: email_address_o *clone () const
SYNOPSIS: Makes a perfect copy (a "clone") of the current object.
RETURNS: a pointer to a newly made email_address_o instance.
 

send_message()
SIGNATURE: int send_message (const string_o &smess, int *pi, boolean isfile = FALSE)
SYNOPSIS:
This function mails a message that gets passed in via a string object. The recipient, and all other parameters required by the e-mail server (the MTA), must have been set prior to calling this function. The entire text of the message is in input parameter 'smess'. There is only nominal checking to verify if a message was successfully delivered (on the unix side, there is basically none).
For e-mailing a message with file attachments, use the member function send_files() .
PARAMETERS

• smess: string object containing the body of the message to e-mail. This message should not contain any e-mail header lines (eg, "From: myacct@sender.org") - use other member function calls to set the appropriate e-mail property. For type "text/html", the start of the string would probably contain text like so:
  

  
    
    
      [my raw text]
    
  

• pi: error indicator variable. The values this output parameter is as follows:
  0: ok; the message was sent on its way to the recipient
  1: the recipient address was not set
  2: need the "From" field; it was not set [use "set_from()"]
  3: "MTA" (e-mail server) name was not set
  4: could not connect to the MTA (the e-mail server)
  5: 'system()' system call failure [unix side only]
  6: COM error - "CoCreateInstance() #1"
  7: COM error - "CoCreateInstance() #2"
  8: unsupported OS [should never happen]
  9: unknown error on the "Send()" [needs to be investigated]
  10: impossible case value (this should definitely never happen)

RETURNS:
0: the message was sent
-1: an error ocurred in trying to send the message (see value of output parameter 'pi')
 

send_files()
SIGNATURE: int send_files (const string_o &smess, list_o &fl, int *pi)
SYNOPSIS:
Sends an e-mail message with file attachments. This function is analogous to "send_message()" (see that function for a description of the 'send' functionality and 'smess' parameter). This function takes a list of file names, provided as a list in the second parameter, 'fl'.
PARAMETERS

• smess: string object containing the body of the message to e-mail.
• pi: error indicator variable. The values this output parameter is the same as for "send_message()" - see that function for these values.

 

bad_reference()
SIGNATURE: const email_address_o &bad_reference ()
SYNOPSIS:
returns a reference "handle" to the "bad email address object" instance. This is used mainly for containers, where an object must be returned, whether or not there is one that satisfies the operation (such as a search for a particular object in a list).
 

is_valid_syntax()
SIGNATURE: boolean is_valid_syntax (const string_o &sa, int *pi = NULL)
SYNOPSIS:
returns TRUE or FALSE if the string contents of 'sa' appears to be a valid e-mail address. Note that this should not be the unix-style "account only" format, eg, it should contain an '@' and a domain component.
RETURNS:
TRUE: the address is valid
FALSE: the address is invalid
 

operator <<()
SIGNATURE: friend std::ostream &operator << (std::ostream &, const email_address_o &)
SYNOPSIS: dumps the e-mail address to an ostream. This will print out the e-mail address. It maps onto a "print()" function call.
 

z_lookslike_failedmail()
SIGNATURE: boolean z_lookslike_failedmail (email_o &msg, string_o &sa, int *pi = NULL)
SYNOPSIS:
this looks at the subject line and body text of the e-mail, trying to determine if the mail is "bounced mail" due to a failed delivery attempt
PARAMETERS

• msg: the e-mail object to check
• sa: the address of the resultant e-mail.note that [often] there can be multiple e-mail addresses in a failed-to- deliver message; this routine can support at most one.
• pi: [output] error indicator variable. The values this output parameter can assume:
  0: success
  zErr_NoMatch: e-mail address could not be obtained (set only when return value is TRUE) _ zErr_Data_Unexpected: no '<' found, when it must be there zErr_TooMany: more than 1 e-mail address was found (this routine can provide either 0 or 1 addresses). Note, this value is a warning - not an error condision.

DESCRIPTION:
given a message such as this:

the following message to root@xyz.com was undeliverable

or

"delivery to the following recipient failed permanently:
 
  somebody@hal9000-sample.org

If these text passages are part of the body text of input parameter 'msg', this routine will return TRUE. If no such messages are found, it returns FALSE. This subroutine implements common text formats for bounced mail notifications. The text provided in such messages can be customized, so clearly not all texts are implemented. This subroutine is a best-guess attempt at ferreting out such mail.
 

z_str_lookslike_emailaddr()
SIGNATURE: boolean z_str_lookslike_emailaddr (const string_o &s)
SYNOPSIS:
this tests the given string ('s') to see if it appears to be a valid e-mail address. this is a loose check, and is exactly equivalent to email_address_o::is_valid_syntax().
RETURNS:
TRUE: the address appears to be a valid address
FALSE: the address appears to be an invalid address
 

note.
Almost any string containing a '@' in it will be accepted as a valid e-mail address by this object. The rules for e-mail addresses are surprisingly lax. The email_address_o class used to be sub-classed from the internet_address_o class (see header file 'z_arpaaddr.h'). It was decided that this was an incorrect implementation, and now they are sibling classes. The internet address object can store a computer address as a set of IP octets (IPv4). Probably little reusable functionality could be reaped by subclassing the email address from the internet address.

Each e-mail address object carries a "_dflt_to_curr_host" flag. This is always TRUE if the object is inside a unix type OS. The purpose of the flag is determine if acount naem-only type e-mail addresses are to be permitted (ie, "@mydomain.com" compnent of a full typical e-mail address is not required). This is used within set_recipient() .

examples.
this example shows how you can send thousands (or more) e-mails in a few short lines of code.
Note: although the addresses in this example are supplied for demonstration purposes only, we combed our databank of contacts for the worst of the worst (what you do with it is up to you).

static char *spam_bomb[] =
{
    "gary.dale@centric.co.uk",
    "major@ksi-corp.com",
    "caswell@watson.ibm.com",
    "wmondelli@cmaeti.com",
    NULL
};

#define MY_MSG "Hello. Remember me?\nI just want to shove you this note.\n"

void main()
{
    int i, ie;
    string_o s_body = MY_MSG;
    email_address_o emx;
    emx.set_from ("me@gmail.com");
    emx.set_mta  ("smtp.gmail.com");
    emx.set_port (465);
    emx.set_subject("This is how to send e-mail in C++");
    for (i = 0; spam_bomb[i] != NULL; i++)
        ie = emx.send_message (s_body, &iex);
}

history.

Sat 03/21/1998: {13:30:01 EST} created
??? 07/04/1998: added perma-storage capability
??? 07/06/1998: heavy modifications. added octets
??? 07/13/1998: changed "serial" -> "int unique" (the new orthodoxy)
??? 10/13/1998: print() added using "free_text" field
Sat 10/24/1998: set_old() made non-inline, synced w. data-bag
??? 07/19/1998: folding in the ip_address data-bag material
Sun 08/26/2001: Vladimir V. & Anton A. doing Microsoft implementation
??? 06/01/2002: new macro nomenclature standards: "zos_", "zcc_"
Mon 09/09/2002: changing DB field "name" -> "free_text"
??? 10/04/2002: changed base class; was 'internet_address_o'
Sat 05/26/2012: name change: "set_show_options()" -> "set_showopts()"
Sun 10/06/2002: took out link to arpa_address former-parent-object
Wed 02/09/2011: {12:45am} disabled 'send' functionality
Sun 05/27/2012: set_recipient() bug fix; send_message() clean-up [--GeG]
Thu 05/31/2012: finding questionable code in operator = (rec_dbag_o &)