m_verify.h

/* The MIT License (MIT)
 * 
 * Copyright (c) 2017 Monetra Technologies, LLC.
 * 
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 * 
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 * 
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 * THE SOFTWARE.
 */
 
 
#ifndef M_EMAIL_VERIFY_H
#define M_EMAIL_VERIFY_H
 
 
/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */
 
#include <mstdlib/base/m_defs.h>
#include <mstdlib/base/m_types.h>
 
/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */
 
__BEGIN_DECLS
 
/*! \addtogroup m_verify Verification
 *  \ingroup m_text
 *
 * \brief Validation of strings against various standards (email address, domain name, etc.).
 * 
 * @{
 */
 
typedef enum {
    M_VERIFY_EMAIL_LISTDELIM_AUTO = 0,
    M_VERIFY_EMAIL_LISTDELIM_SEMICOLON,
    M_VERIFY_EMAIL_LISTDELIM_COMMA,
} M_verify_email_listdelim_t;
 
 
/*! Verify that the given single email address is valid.
 * 
 * An email address is composed of the following parts:
 * \verbatim display_name<local_part@domain>\endverbatim
 * 
 * The display name may contain double-quotes. Within double-quotes, the full range of symbols may be used (dot,
 * comma, semicolon, at, escaped double-quote, etc.). The space and tab characters are allowed in the display name,
 * even outside of quotes.
 * 
 * If the display name is not provided, the angle brackets around the rest of the email address are optional.
 * 
 * This email address validator differs from the RFC standards for email in the following ways:
 * 
 * \li Double quotes are not allowed, except in the display name (a.k.a. friendly name).
 * \li Comments (chunks of text enclosed by parentheses) are not allowed, though parenthesis are allowed in the
 *     display name if they're surrounded by double-quotes.
 * \li Consecutive dots are allowed in the local part of the address, since they are accepted by gmail.
 * \li Only the following non-alphanumeric characters are allowed in the local part: \verbatim '*+-=^_{}.~ \endverbatim
 * \li IP address domains are not allowed (e.g., joe.smith\@[192.168.2.1] is invalid).
 * \li UTF-8 is not allowed in any part of the address (display name, local part, or domain name).
 * 
 * Example of valid address:
 * \verbatim "Public, John Q. (Support)" <jq..public+support@generic-server.com> \endverbatim
 * 
 * \see M_verify_email_address_list
 * 
 * \param[in] addr  email address to verify
 * \return          TRUE if the address is valid
 */
M_API M_bool M_verify_email_address(const char *addr);
 
 
/*! Verify that the given domain name is valid.
 * 
 * Valid domain names are composed of letters, digits, and hyphens ('-'), separated into sections
 * by dots ('.'). Each section is limited to 63 chars, and may not begin or end with a hyphen.
 * The entire domain name is limited to 253 characters - note that a 253 character domain name
 * takes 255 bytes to store with the length-prefixed encoding used by DNS.
 * 
 * \param[in] dname  domain name to verify
 * \return           TRUE if the domain name is valid
 */
M_API M_bool M_verify_domain(const char *dname);
 
 
/*! Verify that the given list of email addresses is valid.
 * 
 * The list may be delimited by either commas (',') or semicolons (';'), but not both.
 * This function limits the number of addresses in the list to 100 - this isn't a true
 * standard, but it's the limit used virutally everywhere in practice.
 * 
 * The list parser is tolerant of whitespace - individual addresses are trimmed before they're
 * passed to the email address validator.
 * 
 * The individual addresses in the list may include display names (a.k.a friendly names).
 * 
 * \see M_verify_email_address
 * 
 * \param[in] addr_list  list of email addresses to verify
 * \param[in] delim_type Type of delimiter to expect. Can be auto detected.
 * \return               TRUE if the list and all emails in it are valid
 */
M_API M_bool M_verify_email_address_list(const char *addr_list, M_verify_email_listdelim_t delim_type);
 
/*! @} */
 
__END_DECLS
 
#endif /* M_EMAIL_VERIFY_H */