An interface representing an address book card. More...

import "nsIAbCard.idl";

Inheritance diagram for nsIAbCard:

Collaboration diagram for nsIAbCard:

Public Member Functions
nsIVariant	getProperty (in AUTF8String name, in nsIVariant defaultValue)
	Returns a property for the given name.
void	deleteProperty (in AUTF8String name)
	Deletes the property with the given name.
boolean	hasEmailAddress (in AUTF8String aEmailAddress)
	Determines whether or not a card has the supplied email address in either of its PrimaryEmail or SecondEmail attributes.
AUTF8String	translateTo (in AUTF8String aType)
	Translates a card into a specific format.
AString	generatePhoneticName (in boolean aLastNameFirst)
	Translates a card from the specified format.
void	copy (in nsIAbCard aSrcCard)
	This function will copy all values from one card to another.
boolean	equals (in nsIAbCard aCard)
	Returns true if this card is equal to the other card.


AString	getPropertyAsAString (in string name)
	Returns a property for the given name.
AUTF8String	getPropertyAsAUTF8String (in string name)
	Returns a property for the given name.
PRUint32	getPropertyAsUint32 (in string name)
	Returns a property for the given name.
boolean	getPropertyAsBool (in string name)
	Returns a property for the given name.


void	setProperty (in AUTF8String name, in nsIVariant value)
	Assigns the given to value to the property of the given name.
void	setPropertyAsAString (in string name, in AString value)
	Assigns the given to value to the property of the given name.
void	setPropertyAsAUTF8String (in string name, in AUTF8String value)
	Assigns the given to value to the property of the given name.
void	setPropertyAsUint32 (in string name, in PRUint32 value)
	Assigns the given to value to the property of the given name.
void	setPropertyAsBool (in string name, in boolean value)
	Assigns the given to value to the property of the given name.
Public Attributes
readonly attribute nsISimpleEnumerator	properties
	A list of all the properties that this card has as an enumerator, whose members are all nsIProperty objects.
attribute boolean	isMailList
attribute string	mailListURI
	If isMailList is true then mailListURI will contain the URI of the associated mail list.


attribute AString	firstName
	These properties are shorthand for getProperty and setProperty.
attribute AString	lastName
	These properties are shorthand for getProperty and setProperty.
attribute AString	displayName
	These properties are shorthand for getProperty and setProperty.
attribute AString	primaryEmail
	These properties are shorthand for getProperty and setProperty.

Detailed Description

An interface representing an address book card.

Fundamentally, it 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)
Boolean properties:
- AllowRemoteContent
Photo properties:
- PhotoName
- PhotoType
- PhotoURI

Member Function Documentation

void nsIAbCard::copy ( in nsIAbCard aSrcCard )

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

Parameters:

srcCard

The source card to copy values from.

void nsIAbCard::deleteProperty ( in AUTF8String name )

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.

Parameters:

name

The case-sensitive name of the property to set.

boolean nsIAbCard::equals ( in nsIAbCard aCard )

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.

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.

Returns:: Equality, as defined above.

Parameters:

aCard

The card to compare against.

AString nsIAbCard::generatePhoneticName ( in boolean aLastNameFirst )

Translates a card from the specified format.

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

Parameters:

aLastNameFirst

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

Returns:: A string containing the generated phonetic name.

nsIVariant nsIAbCard::getProperty	(	in AUTF8String	name,
		in nsIVariant	defaultValue
	)

Returns a property for the given name.

Parameters:

	name	The case-sensitive name of the property to get.
	defaultValue	The value to return if the property does not exist.

Exceptions:

	NS_ERROR_NOT_AVAILABLE	if the named property does not exist.
	NS_ERROR_CANNOT_CONVERT_DATA	if the property cannot be converted to the desired type.

AString nsIAbCard::getPropertyAsAString ( 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."

These functions are marked [noscript] since xpconnect performs automatic type conversion on nsIVariants such that they are not needed for scripts, only for C++ callers.

Parameters:

name

The case-sensitive name of the property to get.

Exceptions:

	NS_ERROR_NOT_AVAILABLE	if the named property does not exist.
	NS_ERROR_CANNOT_CONVERT_DATA	if the property cannot be converted to the desired type.

AUTF8String nsIAbCard::getPropertyAsAUTF8String ( 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."

These functions are marked [noscript] since xpconnect performs automatic type conversion on nsIVariants such that they are not needed for scripts, only for C++ callers.

Parameters:

name

The case-sensitive name of the property to get.

Exceptions:

	NS_ERROR_NOT_AVAILABLE	if the named property does not exist.
	NS_ERROR_CANNOT_CONVERT_DATA	if the property cannot be converted to the desired type.

boolean nsIAbCard::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."

These functions are marked [noscript] since xpconnect performs automatic type conversion on nsIVariants such that they are not needed for scripts, only for C++ callers.

Parameters:

name

The case-sensitive name of the property to get.

Exceptions:

	NS_ERROR_NOT_AVAILABLE	if the named property does not exist.
	NS_ERROR_CANNOT_CONVERT_DATA	if the property cannot be converted to the desired type.

PRUint32 nsIAbCard::getPropertyAsUint32 ( 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."

These functions are marked [noscript] since xpconnect performs automatic type conversion on nsIVariants such that they are not needed for scripts, only for C++ callers.

Parameters:

name

The case-sensitive name of the property to get.

Exceptions:

	NS_ERROR_NOT_AVAILABLE	if the named property does not exist.
	NS_ERROR_CANNOT_CONVERT_DATA	if the property cannot be converted to the desired type.

boolean nsIAbCard::hasEmailAddress ( in AUTF8String aEmailAddress )

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.

Parameters:

aEmailAddress

The email address to attempt to match against.

Returns:: True if aEmailAddress matches any of the email addresses stored in the card.

void nsIAbCard::setProperty	(	in AUTF8String	name,
		in nsIVariant	value
	)

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.

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.

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.

Parameters:

	name	The case-sensitive name of the property to set.
	value	The new value of the property.

void nsIAbCard::setPropertyAsAString	(	in string	name,
		in AString	value
	)

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.

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.

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.

Parameters:

	name	The case-sensitive name of the property to set.
	value	The new value of the property.

void nsIAbCard::setPropertyAsAUTF8String	(	in string	name,
		in AUTF8String	value
	)

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.

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.

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.

Parameters:

	name	The case-sensitive name of the property to set.
	value	The new value of the property.

void nsIAbCard::setPropertyAsBool	(	in string	name,
		in boolean	value
	)

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.

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.

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.

Parameters:

	name	The case-sensitive name of the property to set.
	value	The new value of the property.

void nsIAbCard::setPropertyAsUint32	(	in string	name,
		in PRUint32	value
	)

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.

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.

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.

Parameters: