path: root/comm/mailnews/addrbook/public/nsIAbCard.idl

/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"

interface nsIProperty;
interface nsIStringBundle;
interface nsIVariant;

[scriptable, uuid(97448252-F189-11d4-A422-001083003D0C)]
interface nsIAbPreferMailFormat : nsISupports {
    const unsigned long unknown   = 0;
    const unsigned long plaintext = 1;
    const unsigned long html      = 2;
};

/**
 * An interface representing an address book card.
 *
 * None of these IDs will be reflected in the property collection. Neither
 * nsIAbCard::properties, nsIAbCard::deleteProperty, nor any of the property
 * getters and setters are able to interact with these properties.
 *
 * Fundamentally, a card is a collection of properties. Modifying a property in
 * some way on a card does not change the backend used to store the card; the
 * directory is required to do make the changes here.
 *
 * The following are the core properties that are used:
 * - Names:
 *   - FirstName, LastName
 *   - PhoneticFirstName, PhoneticLastName
 *   - DisplayName, NickName
 *   - SpouseName, FamilyName
 * - PrimaryEmail, SecondEmail
 * - Home Contact:
 *   - HomeAddress, HomeAddress2, HomeCity, HomeState, HomeZipCode, HomeCountry
 *   - HomePhone, HomePhoneType
 * - Work contact. Same as home, but with `Work' instead of `Home'
 * - Other Contact:
 *   - FaxNumber, FaxNumberType
 *   - PagerNumber, PagerNumberType
 *   - CellularNumber, CellularNumberType
 * - JobTitle, Department, Company
 * - _AimScreenName
 * - Dates:
 *   - AnniversaryYear, AnniversaryMonth, AnniversaryDay
 *   - BirthYear, BirthMonth, BirthDay
 * - WebPage1 (work), WebPage2 (home)
 * - Custom1, Custom2, Custom3, Custom4
 * - Notes
 * - Integral properties:
 *   - LastModifiedDate
 *   - PopularityIndex
 * - Photo properties:
 *   - PhotoName
 *   - PhotoType
 *   - PhotoURI
 *
 * The contract id for the standard implementation is
 * <tt>\@mozilla.org/addressbook/cardproperty;1</tt>.
 */
[scriptable, uuid(9bddf024-5178-4097-894e-d84b4ddde101)]
interface nsIAbCard : nsISupports {
  /**
   * @{
   * These constants reflect the possible values of the
   * mail.addr_book.lastnamefirst preferences. They are intended to be used in
   * generateName, defined below.
   */
   const unsigned long GENERATE_DISPLAY_NAME = 0;
   const unsigned long GENERATE_LAST_FIRST_ORDER = 1;
   const unsigned long GENERATE_FIRST_LAST_ORDER = 2;
   /** @} */

  /**
   * Generate a name from the item for display purposes.
   *
   * If this item is an nsIAbCard, then it will use the aGenerateFormat option
   * to determine the string to return.
   * If this item is not an nsIAbCard, then the aGenerateFormat option may be
   * ignored, and the displayName of the item returned.
   *
   * @param  aGenerateFormat The format to generate as per the GENERATE_*
   *                         constants above.
   * @param  aBundle         An optional parameter that is a pointer to a string
   *                         bundle that holds:
   *           chrome://messenger/locale/addressbook/addressBook.properties
   *                         If this bundle is not supplied, then the function
   *                         will obtain the bundle itself. If cached by the
   *                         caller and supplied to this function, then
   *                         performance will be improved over many calls.
   * @return                 A string containing the generated name.
   */
  AString generateName(in long aGenerateFormat,
                       [optional] in nsIStringBundle aBundle);

  /**
   * The UID for the nsIAbDirectory containing this card.
   *
   * The directory considered to contain this card is the directory which
   * produced this card (e.g., through nsIAbDirectory::getCardForProperty) or
   * the last directory to modify this card, if another directory did so. If the
   * last directory to modify this card deleted it, then this card is considered
   * unassociated.
   *
   * If this card is not associated with a directory, this string will be empty.
   *
   * There is no standardized way to associate a card with multiple directories.
   *
   * Consumers of this interface outside of directory implementations SHOULD
   * NOT, in general, modify this property.
   */
  attribute AUTF8String directoryUID;

  /**
   * A 128-bit unique identifier for this card. This can only be set if it is not
   * already set. The getter sets a value if there is not one.
   */
  attribute AUTF8String UID;

  /**
   * A list of all the properties that this card has as an enumerator, whose
   * members are all nsIProperty objects.
   */
  readonly attribute Array<nsIProperty> properties;

  /**
   * Returns a property for the given name.
   *
   * @param name             The case-sensitive name of the property to get.
   * @param defaultValue     The value to return if the property does not exist.
   * @exception NS_ERROR_NOT_AVAILABLE if the named property does not exist.
   * @exception NS_ERROR_CANNOT_CONVERT_DATA if the property cannot be converted
   *                                         to the desired type.
   */
  nsIVariant getProperty(in AUTF8String name, in nsIVariant defaultValue);
  /**
   * @{
   * Returns a property for the given name.  Javascript callers should NOT use these,
   * but use getProperty instead. XPConnect will do the type conversion automagically.
   *
   * These functions convert values in the same manner as the default
   * implementation of nsIVariant. Of particular note is that boolean variables
   * are converted to integers as in C/C++ (true is a non-zero value), so that
   * false will be converted to a string of "0" and not "false."
   *
   *
   * @param name             The case-sensitive name of the property to get.
   * @exception NS_ERROR_NOT_AVAILABLE if the named property does not exist.
   * @exception NS_ERROR_CANNOT_CONVERT_DATA if the property cannot be converted
   *                                         to the desired type.
   */
  AString getPropertyAsAString(in string name);
  AUTF8String getPropertyAsAUTF8String(in string name);
  unsigned long getPropertyAsUint32(in string name);

  /**
   * Returns a property for the given name.
   *
   * @param name             The case-sensitive name of the property to get.
   * @param defaultValue     The value to return if the property does not exist.
   */
  boolean getPropertyAsBool(in string name, in boolean defaultValue);

  /** @} */

  /**
   * Assigns the given to value to the property of the given name.
   *
   * Should the property exist, its value will be overwritten. An
   * implementation may impose additional semantic constraints for certain
   * properties. However, such constraints might not be checked by this method.
   *
   * @warning A value MUST be convertible to a string; if this convention is not
   * followed, consumers of cards may fail unpredictably or return incorrect
   * results.
   *
   * @param name             The case-sensitive name of the property to set.
   * @param value            The new value of the property.
   */
  void setProperty(in AUTF8String name, in nsIVariant value);

  /**
   * @{
   * Sets a property for the given name.  Javascript callers should NOT use these,
   * but use setProperty instead. XPConnect will do the type conversion automagically.
   *
   * These functions convert values in the same manner as the default
   * implementation of nsIVariant.
   */
  void setPropertyAsAString(in string name, in AString value);
  void setPropertyAsAUTF8String(in string name, in AUTF8String value);
  void setPropertyAsUint32(in string name, in unsigned long value);
  void setPropertyAsBool(in string name, in boolean value);

  /** @} */

  /**
   * Deletes the property with the given name.
   *
   * Some properties may not be deleted. However, the implementation will not
   * check this constraint at this method. If such a property is deleted, an
   * error may be thrown when the card is modified at the database level.
   *
   * @param name             The case-sensitive name of the property to set.
   */
  void deleteProperty(in AUTF8String name);

  /**
   * Whether this card supports vCard properties. Currently only AddrBookCard
   * supports vCard properties.
   */
  readonly attribute boolean supportsVCard;

  /**
   * A `VCardProperties` object for this card, or null. If `supportsVCard` is
   * true, this attribute MUST be a `VCardProperties` object, otherwise it
   * MUST be null.
   *
   * @see VCardProperties in VCardUtils.jsm
   */
  readonly attribute jsval vCardProperties;

  /**
   * @{
   * These properties are shorthand for getProperty and setProperty.
   */
  attribute AString firstName;
  attribute AString lastName;
  attribute AString displayName;
  attribute AString primaryEmail;
  /** @} */

  /**
   * All email addresses associated with this card, in order of preference.
   */
  readonly attribute Array<AString> emailAddresses;

  /**
   * Determines whether or not a card has the supplied email address in either
   * of its PrimaryEmail or SecondEmail attributes.
   *
   * Note: This function is likely to be temporary whilst we work out proper
   * APIs for multi-valued attributes in bug 118665.
   *
   * @param  aEmailAddress The email address to attempt to match against.
   * @return               True if aEmailAddress matches any of the email
   *                       addresses stored in the card.
   */
  boolean hasEmailAddress(in AUTF8String aEmailAddress);

  /**
   * A URL to a photo for this card, or an empty string if there isn't one.
   * This is probably a file: or data: URL but other schemes are possible.
   */
  readonly attribute AString photoURL;

  /**
   * Translates a card into a specific format.
   * The following types are supported:
   * - base64xml
   * - xml
   * - vcard
   *
   * @param  aType          The type of item to translate the card into.
   * @return                A string containing the translated card.
   * @exception NS_ERROR_ILLEGAL_VALUE if we do not recognize the type.
   */
  AUTF8String translateTo(in AUTF8String aType);

  /**
   * Translates a card from the specified format
   */
  //void translateFrom(in AUTF8String aType, in AUTF8String aData);

  /**
   * Generate a phonetic name from the card, using the firstName and lastName
   * values.
   *
   * @param  aLastNameFirst  Set to True to put the last name before the first.
   * @return                 A string containing the generated phonetic name.
   */
  AString generatePhoneticName(in boolean aLastNameFirst);

  /**
   * Generate a chat name from the card, containing the value of the
   * first non-empty chat field.
   *
   * @return                 A string containing the generated chat name.
   */
  AString generateChatName();

  /**
   * This function will copy all values from one card to another.
   *
   * @param  srcCard         The source card to copy values from.
   */
  void copy(in nsIAbCard aSrcCard);

  /**
   * Returns true if this card is equal to the other card.
   *
   * The default implementation defines equal as this card pointing to the
   * same object as @arg aCard; another implementation defines it as equality of
   * properties and values.
   *
   * @warning The exact nature of equality is still undefined, and actual
   *          results may not match theoretical results. Most notably, the code
   *          <tt>a.equals(b) == b.equals(a)</tt> might not return true. In
   *          particular, calling equals on cards from different address books
   *          may return inaccurate results.
   *
   *
   * @return                 Equality, as defined above.
   * @param  aCard           The card to compare against.
   */
  boolean equals(in nsIAbCard aCard);

  // PROPERTIES TO BE DELETED AS PART OF REWRITE

  attribute boolean isMailList;
  /**
   * If isMailList is true then mailListURI
   * will contain the URI of the associated
   * mail list
   */
  attribute string mailListURI;
};

%{C++
// A nice list of properties for the benefit of C++ clients
#define kUIDProperty                "UID"
#define kFirstNameProperty          "FirstName"
#define kLastNameProperty           "LastName"
#define kDisplayNameProperty        "DisplayName"
#define kNicknameProperty           "NickName"
#define kPriEmailProperty           "PrimaryEmail"
#define kLastModifiedDateProperty   "LastModifiedDate"
#define kPopularityIndexProperty    "PopularityIndex"

#define kPhoneticFirstNameProperty  "PhoneticFirstName"
#define kPhoneticLastNameProperty   "PhoneticLastName"
#define kSpouseNameProperty         "SpouseName"
#define kFamilyNameProperty         "FamilyName"
#define k2ndEmailProperty           "SecondEmail"

#define kHomeAddressProperty        "HomeAddress"
#define kHomeAddress2Property       "HomeAddress2"
#define kHomeCityProperty           "HomeCity"
#define kHomeStateProperty          "HomeState"
#define kHomeZipCodeProperty        "HomeZipCode"
#define kHomeCountryProperty        "HomeCountry"
#define kHomeWebPageProperty        "WebPage2"

#define kWorkAddressProperty        "WorkAddress"
#define kWorkAddress2Property       "WorkAddress2"
#define kWorkCityProperty           "WorkCity"
#define kWorkStateProperty          "WorkState"
#define kWorkZipCodeProperty        "WorkZipCode"
#define kWorkCountryProperty        "WorkCountry"
#define kWorkWebPageProperty        "WebPage1"

#define kHomePhoneProperty          "HomePhone"
#define kHomePhoneTypeProperty      "HomePhoneType"
#define kWorkPhoneProperty          "WorkPhone"
#define kWorkPhoneTypeProperty      "WorkPhoneType"
#define kFaxProperty                "FaxNumber"
#define kFaxTypeProperty            "FaxNumberType"
#define kPagerTypeProperty          "PagerNumberType"
#define kPagerProperty              "PagerNumber"
#define kCellularProperty           "CellularNumber"
#define kCellularTypeProperty       "CellularNumberType"

#define kJobTitleProperty           "JobTitle"
#define kDepartmentProperty         "Department"
#define kCompanyProperty            "Company"
#define kScreenNameProperty         "_AimScreenName"
#define kCustom1Property            "Custom1"
#define kCustom2Property            "Custom2"
#define kCustom3Property            "Custom3"
#define kCustom4Property            "Custom4"
#define kNotesProperty              "Notes"

#define kGtalkProperty              "_GoogleTalk"
#define kAIMProperty                "_AimScreenName"
#define kYahooProperty              "_Yahoo"
#define kSkypeProperty              "_Skype"
#define kQQProperty                 "_QQ"
#define kMSNProperty                "_MSN"
#define kICQProperty                "_ICQ"
#define kXMPPProperty               "_JabberId"
#define kIRCProperty                "_IRC"

#define kAnniversaryYearProperty    "AnniversaryYear"
#define kAnniversaryMonthProperty   "AnniversaryMonth"
#define kAnniversaryDayProperty     "AnniversaryDay"
#define kBirthYearProperty          "BirthYear"
#define kBirthMonthProperty         "BirthMonth"
#define kBirthDayProperty           "BirthDay"
%}