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