Public Member Functions | Public Attributes

nsIAbCard Interface Reference

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

import "nsIAbCard.idl";

Inheritance diagram for nsIAbCard:
Collaboration diagram for nsIAbCard:

List of all members.

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:


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:
name The case-sensitive name of the property to set.
value The new value of the property.
AUTF8String nsIAbCard::translateTo ( in AUTF8String  aType  ) 

Translates a card into a specific format.

The following types are supported:

  • base64xml
  • xml
  • vcard
Parameters:
aType The type of item to translate the card into.
Returns:
A string containing the translated card.
Exceptions:
NS_ERROR_ILLEGAL_VALUE if we do not recognize the type.

Member Data Documentation

attribute AString nsIAbCard::displayName

These properties are shorthand for getProperty and setProperty.

attribute AString nsIAbCard::firstName

These properties are shorthand for getProperty and setProperty.

attribute AString nsIAbCard::lastName

These properties are shorthand for getProperty and setProperty.

attribute string nsIAbCard::mailListURI

If isMailList is true then mailListURI will contain the URI of the associated mail list.

attribute AString nsIAbCard::primaryEmail

These properties are shorthand for getProperty and setProperty.

A list of all the properties that this card has as an enumerator, whose members are all nsIProperty objects.


The documentation for this interface was generated from the following file: