nsIAbCard/Thunderbird3

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:
  • LastModifiedDate
  • PopularityIndex
  • PreferMailFormat (see nsIAbPreferMailFormat)
• Boolean properties:
  • AllowRemoteContent

web.html($0) is defined in wiki.template('tbsource', mediawiki.args([$1])). It is wiki.template(mediawiki.path('InterfaceStatus:Scriptable_' + $4, "en")) and wiki.template(mediawiki.path('InterfaceStatus:' + $2, "en"), mediawiki.args([$3])).

Inherits from: nsIAbItem

Method overview

Attributes

Methods

getProperty()

Returns a property for the given name.

 nsIVariant getProperty(in AUTF8String name, in nsIVariant defaultValue);

Parameters

<tt>name</tt>

The case-sensitive name of the property to get.

<tt>defaultValue</tt>

The value to return if the property does not exist.

Return value

The value of the attribute asked for.

Exceptions Thrown

<tt>NS_ERROR_NOT_AVAILABLE<tt> </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

<tt>name</tt>

The case-sensitive name of the property to get.

Return value

The value of the attribute asked for.

Exceptions Thrown

<tt>NS_ERROR_NOT_AVAILABLE<tt> </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.

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

<tt>name</tt>

The case-sensitive name of the property to set.

<tt>value</tt>

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

<tt>name</tt>

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

<tt>aType</tt>

The type of item to translate the card into.

Return value

A string containing the translated card.

Exceptions Thrown

<tt>NS_ERROR_ILLEGAL_VALUE</tt>

Type not recognized.

copy()

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

void copy(in nsIAbCard srcCard)

Parameters

<tt>srcCard</tt>

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.

boolean equals(in nsIAbCard card)

Parameters

<tt>card</tt>

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

<tt>aLastNameFirst</tt>

Set to true to put the last name before the first.

Return value

A string containing the generated phonetic name.