summaryrefslogtreecommitdiffstats
path: root/mailnews/addrbook/public/nsIAbCard.idl
diff options
context:
space:
mode:
Diffstat (limited to 'mailnews/addrbook/public/nsIAbCard.idl')
-rw-r--r--mailnews/addrbook/public/nsIAbCard.idl358
1 files changed, 358 insertions, 0 deletions
diff --git a/mailnews/addrbook/public/nsIAbCard.idl b/mailnews/addrbook/public/nsIAbCard.idl
new file mode 100644
index 000000000..ccd1c4c43
--- /dev/null
+++ b/mailnews/addrbook/public/nsIAbCard.idl
@@ -0,0 +1,358 @@
+/* -*- 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 "nsIAbItem.idl"
+
+interface nsISimpleEnumerator;
+interface nsIVariant;
+
+[scriptable, uuid(97448252-F189-11d4-A422-001083003D0C)]
+interface nsIAbPreferMailFormat {
+ const unsigned long unknown = 0;
+ const unsigned long plaintext = 1;
+ const unsigned long html = 2;
+};
+
+/**
+ * An interface representing an address book card.
+ *
+ * The UUID of a card is a composition of a directory ID and a per-directory ID.
+ * The per-directory ID is reflected in the localId property. If either of these
+ * properties change, the UUID will change correspondingly.
+ *
+ * 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
+ * - PreferMailFormat (see nsIAbPreferMailFormat)
+ * - 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 : nsIAbItem {
+ /**
+ * The UUID 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 directoryId;
+
+ /**
+ * The per-directory ID of this card.
+ *
+ * This property is the second part of the tuple logically representing a card
+ * UUID. It shares many requirements with that of nsIAbItem::uuid. In
+ * particular:
+ * - It MUST be unique (within the scope of its directory).
+ * - The empty string MUST only be used to indicate that it has not yet been
+ * assigned a localId.
+ * - It is STRONGLY RECOMMENDED that this id is consistent across sessions and
+ * that, should the card be deleted, its ids will not be reused.
+ * - The format of localId is left undefined.
+ *
+ * As long as directoryId is not changed, this property SHOULD NOT be changed.
+ * If directoryId is changed, the new directory MAY choose to reuse the same
+ * localId if reasonable. However, consumers MUST NOT assume that two cards
+ * with different directoryIds but the same localId are logically the same
+ * card.
+ *
+ * Similar to directoryId, consumers of cards outside of directory
+ * implementations SHOULD NOT, in general, modify this property.
+ */
+ attribute AUTF8String localId;
+
+ /**
+ * A list of all the properties that this card has as an enumerator, whose
+ * members are all nsIProperty objects.
+ */
+ readonly attribute nsISimpleEnumerator 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);
+ boolean getPropertyAsBool(in string name);
+
+ /** @} */
+
+ /**
+ * 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);
+
+ /**
+ * @{
+ * These properties are shorthand for getProperty and setProperty.
+ */
+ attribute AString firstName;
+ attribute AString lastName;
+ attribute AString displayName;
+ attribute AString primaryEmail;
+ /** @} */
+
+ /**
+ * 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);
+
+ /**
+ * 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 kFirstNameProperty "FirstName"
+#define kLastNameProperty "LastName"
+#define kDisplayNameProperty "DisplayName"
+#define kNicknameProperty "NickName"
+#define kPriEmailProperty "PrimaryEmail"
+#define kPreferMailFormatProperty "PreferMailFormat"
+#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"
+%}