/* -*- 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
* \@mozilla.org/addressbook/cardproperty;1.
*/
[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 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 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
* a.equals(b) == b.equals(a) 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"
%}