diff options
Diffstat (limited to 'comm/mailnews/addrbook/public/nsIAbCard.idl')
| -rw-r--r-- | comm/mailnews/addrbook/public/nsIAbCard.idl | 402 |
1 files changed, 402 insertions, 0 deletions
diff --git a/comm/mailnews/addrbook/public/nsIAbCard.idl b/comm/mailnews/addrbook/public/nsIAbCard.idl new file mode 100644 index 0000000000..69acf7fa95 --- /dev/null +++ b/comm/mailnews/addrbook/public/nsIAbCard.idl @@ -0,0 +1,402 @@ +/* -*- 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" +%} |