nsIAbCard/Thunderbird3

Note: This interface has been overhauled completely for Thunderbird 3. Documentation for the old nsIAbCard interface is currently at nsIAbCard.

The nsIAbCard interface is used to represent and manipulate cards in the address book. In a big change from the original nsIAbCard, properties are now stored in a hash table instead of as attributes on the interface, allowing it to be more flexible.

Properties currently supported on the card:

  • 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:
  • Boolean properties:
    • AllowRemoteContent

Inherits from: nsIAbItem

Method overview

nsIVariant getProperty(in AUTF8String name, in nsIVariant defaultValue);
[noscript] AString getPropertyAsAString(in string name);
[noscript] AUTF8String getPropertyAsAUTF8String(in string name);
[noscript] PRUint32 getPropertyAsUint32(in string name);
[noscript] boolean getPropertyAsBool(in string name);
void setProperty(in AUTF8String name, in nsIVariant value);
[noscript] void setPropertyAsAString(in string name, in AString value);
[noscript] void setPropertyAsAUTF8String(in string name, in AUTF8String value);
[noscript] void setPropertyAsUint32(in string name, in PRUint32 value);
[noscript] void setPropertyAsBool(in string name, in boolean value);
void deleteProperty(in AUTF8String name);
AUTF8String translateTo(in AUTF8String aType);
void copy(in nsIAbCard srcCard)
boolean equals(in nsIAbCard card)
AString generatePhoneticName(in boolean aLastNameFirst)

Attributes

Attribute Type Description
properties nsISimpleEnumerator Readonly: A list of all the properties that this card has as an enumerator, whose members are all nsIProperty objects.
firstName AString Shorthand for getProperty and setProperty.
lastName AString Shorthand for getProperty and setProperty.
displayName AString Shorthand for getProperty and setProperty.
primaryEmail AString Shorthand for getProperty and setProperty.
isMailList boolean If isMailList is true then mailListURI will contain the URI of the associated mail list.
This will be removed from the interface at a later date.
mailListURI string If isMailList is true then mailListURI will contain the URI of the associated mail list.
This will be removed from the interface at a later date.

Methods

getProperty()

Returns a property for the given name.

 nsIVariant getProperty(in AUTF8String name, in nsIVariant defaultValue);
Parameters
name
The case-sensitive name of the property to get.
defaultValue
The value to return if the property does not exist.
Return value
The value of the attribute asked for.
Exceptions Thrown
NS_ERROR_NOT_AVAILABLE<tt>
If the named property does not exist.
<tt>NS_ERROR_CANNOT_CONVERT_DATA
If the property cannot be converted to the desired type.

getPropertyAsAString()

getPropertyAsAUTF8String()

getPropertyAsUint32()

getPropertyAsBool()

 [noscript] AString getPropertyAsAString(in string name);
 [noscript] AUTF8String getPropertyAsAUTF8String(in string name);
 [noscript] PRUint32 getPropertyAsUint32(in string name);
 [noscript] boolean getPropertyAsBool(in string name);

Returns a property for the given name. 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<code>.

These functions are marked <code>[noscript] since XPCconnect performs automatic type conversion on nsIVariant such that they are not needed for scripts, only for C++ callers.

Parameters
name
The case-sensitive name of the property to get.
Return value
The value of the attribute asked for.
Exceptions Thrown
NS_ERROR_NOT_AVAILABLE<tt>
If the named property does not exist.
<tt>NS_ERROR_CANNOT_CONVERT_DATA
If the property cannot be converted to the desired type.
 [noscript] AString getPropertyAsAString(in string name);
 [noscript] AUTF8String getPropertyAsAUTF8String(in string name);
 [noscript] PRUint32 getPropertyAsUint32(in string name);
 [noscript] boolean getPropertyAsBool(in string name);

setProperty()

setPropertyAsAString()

setPropertyAsAUTF8String()

setPropertyAsUint32()

setPropertyAsBool()

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.

These functions convert values in the same manner as the default implementation of nsIVariant.

A value MUST be convertible to a string; if this convention is not followed, consumers of cards may fail unpredictably or return incorrect results.

The non-variant functions are marked [noscript] since XPConnect uses magic with nsIVariant such that the other functions are not needed, although C++ does need them.

 void setProperty(in AUTF8String name, in nsIVariant value);
 [noscript] void setPropertyAsAString(in string name, in AString value);
 [noscript] void setPropertyAsAUTF8String(in string name, in AUTF8String value);
 [noscript] void setPropertyAsUint32(in string name, in PRUint32 value);
 [noscript] void setPropertyAsBool(in string name, in boolean value);
Parameters
name
The case-sensitive name of the property to set.
value
The new value of the property.

deleteProperty()

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.

 void deleteProperty(in AUTF8String name);
Parameters
name
The case-sensitive name of the property to set.

translateTo()

Translates a card into a specific format. The following types are supported:

  • base64xml
  • xml
  • vcard
 AUTF8String translateTo(in AUTF8String aType);
Parameters
aType
The type of item to translate the card into.
Return value

A string containing the translated card.

Exceptions Thrown
NS_ERROR_ILLEGAL_VALUE
Type not recognized.

copy()

This function will copy all values from one card to another.

void copy(in nsIAbCard srcCard)
Parameters
srcCard
The source card to copy values from.

equals()

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 aCard. Another implementation defines it as equality of properties and values.

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.
boolean equals(in nsIAbCard card)
Parameters
card
The card you are comparing with.
Return value
true if the cards are the same.

generatePhoneticName()

Generate a phonetic name from the card, using the firstName and lastName values.

AString generatePhoneticName(in boolean aLastNameFirst)
Parameters
aLastNameFirst
Set to true to put the last name before the first.
Return value
A string containing the generated phonetic name.