mozilla

Revision 162370 of nsIAbCard/Thunderbird3

  • Revision slug: nsIAbCard_Thunderbird3
  • Revision title: nsIAbCard/Thunderbird3
  • Revision id: 162370
  • Created:
  • Creator: Sheppy
  • Is current revision? Yes
  • Comment minor typo fixnsIAbCard//Thunderbird3 nsIAbCard_Thunderbird3

Revision Content

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


{{ Thunderbird-InterfaceStatus("nsIAbCard", "/mailnews/addrbook/public/nsIAbCard.idl", "unfrozen", "Mozilla 1.9", "yes") }}

Inherits from: {{ Interface("nsIAbItem") }}

Method overview

nsIVariant getProperty(in AUTF8String name, in nsIVariant defaultValue);
{{ mediawiki.external('noscript') }} AString getPropertyAsAString(in string name);
{{ mediawiki.external('noscript') }} AUTF8String getPropertyAsAUTF8String(in string name);
{{ mediawiki.external('noscript') }} PRUint32 getPropertyAsUint32(in string name);
{{ mediawiki.external('noscript') }} boolean getPropertyAsBool(in string name);
void setProperty(in AUTF8String name, in nsIVariant value);
{{ mediawiki.external('noscript') }} void setPropertyAsAString(in string name, in AString value);
{{ mediawiki.external('noscript') }} void setPropertyAsAUTF8String(in string name, in AUTF8String value);
{{ mediawiki.external('noscript') }} void setPropertyAsUint32(in string name, in PRUint32 value);
{{ mediawiki.external('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 {{ Interface("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
<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>{{ mediawiki.external('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.

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 {{ mediawiki.external('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.

The exact nature of equality is still undefined, and actual results may not match theoretical results. Most notably, the code <tt>a.equals(b) == b.equals(a)</tt> might not return true. In particular, calling equals on cards from different address books may return inaccurate results.
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.

Revision Source

<p>
</p>
<div class="note"><b>Note:</b> This interface has been overhauled completely for Thunderbird 3. Documentation for the <b>old</b> nsIAbCard interface is currently at <a href="en/NsIAbCard">nsIAbCard</a>.</div>
<p>The <code>nsIAbCard</code> interface is used to represent and manipulate cards in the address book. In a big change from the original <code>nsIAbCard</code>, properties are now stored in a hash table instead of as attributes on the interface, allowing it to be more flexible.
</p><p>Properties currently supported on the card:
</p>
<ul><li> Names:
<ul><li> FirstName, LastName
</li><li> PhoneticFirstName, PhoneticLastName
</li><li> DisplayName, NickName
</li><li> SpouseName, FamilyName
</li><li> PrimaryEmail, SecondEmail
</li></ul>
</li><li> Home Contact:
<ul><li> HomeAddress, HomeAddress2, HomeCity, HomeState, HomeZipCode, HomeCountry
</li><li> HomePhone, HomePhoneType
</li></ul>
</li><li> Work contact. Same as home, but with `Work' instead of `Home'
</li><li> Other Contact:
<ul><li> FaxNumber, FaxNumberType
</li><li> PagerNumber, PagerNumberType
</li><li> CellularNumber, CellularNumberType
</li><li> JobTitle, Department, Company
</li><li> _AimScreenName
</li></ul>
</li><li> Dates:
<ul><li> AnniversaryYear, AnniversaryMonth, AnniversaryDay
</li><li> BirthYear, BirthMonth, BirthDay
</li></ul>
</li><li> WebPage1 (work), WebPage2 (home)
</li><li> Custom1, Custom2, Custom3, Custom4
</li><li> Notes
</li></ul>
<ul><li> Integral properties:
<ul><li> LastModifiedDate
</li><li> PopularityIndex
</li><li> PreferMailFormat (see <a href="en/NsIAbPreferMailFormat">nsIAbPreferMailFormat</a>)
</li></ul>
</li><li> Boolean properties:
<ul><li> AllowRemoteContent
</li></ul>
</li></ul>
<p><br>
{{ Thunderbird-InterfaceStatus("nsIAbCard", "/mailnews/addrbook/public/nsIAbCard.idl", "unfrozen", "Mozilla 1.9", "yes") }}
</p><p>Inherits from: {{ Interface("nsIAbItem") }}
</p>
<h2 id="Method_overview" name="Method_overview">Method overview</h2>
<table class="standard-table"> <tbody><tr>
<td> <code><a href="en/NsIVariant">nsIVariant</a> <a href="#getProperty.28.29">getProperty</a>(in AUTF8String name, in <a href="en/NsIVariant">nsIVariant</a> defaultValue);</code>
</td></tr>
<tr>
<td> <code>{{ mediawiki.external('noscript') }} AString <a href="#getPropertyAsAString.28.29">getPropertyAsAString</a>(in string name);</code>
</td></tr>
<tr>
<td> <code>{{ mediawiki.external('noscript') }} AUTF8String <a href="#getPropertyAsAUTF8String.28.29">getPropertyAsAUTF8String</a>(in string name);</code>
</td></tr>
<tr>
<td> <code>{{ mediawiki.external('noscript') }} PRUint32 <a href="#getPropertyAsUint32.28.29">getPropertyAsUint32</a>(in string name);</code>
</td></tr>
<tr>
<td> <code>{{ mediawiki.external('noscript') }} boolean <a href="#getPropertyAsBool.28.29">getPropertyAsBool</a>(in string name);</code>
</td></tr>
<tr>
<td> <code>void <a href="#setProperty.28.29">setProperty</a>(in AUTF8String name, in <a href="en/NsIVariant">nsIVariant</a> value);</code>
</td></tr>
<tr>
<td> <code>{{ mediawiki.external('noscript') }} void <a href="#setPropertyAsAString.28.29">setPropertyAsAString</a>(in string name, in AString value);</code>
</td></tr>
<tr>
<td> <code>{{ mediawiki.external('noscript') }} void <a href="#setPropertyAsAUTF8String.28.29">setPropertyAsAUTF8String</a>(in string name, in AUTF8String value);</code>
</td></tr>
<tr>
<td> <code>{{ mediawiki.external('noscript') }} void <a href="#setPropertyAsUint32.28.29">setPropertyAsUint32</a>(in string name, in PRUint32 value);</code>
</td></tr>
<tr>
<td> <code>{{ mediawiki.external('noscript') }} void <a href="#setPropertyAsBool.28.29">setPropertyAsBool</a>(in string name, in boolean value);</code>
</td></tr>
<tr>
<td> <code>void <a href="#deleteProperty.28.29">deleteProperty</a>(in AUTF8String name);</code>
</td></tr>
<tr>
<td> <code>AUTF8String <a href="#translateTo.28.29">translateTo</a>(in AUTF8String aType);</code>
</td></tr>
<tr>
<td> <code>void <a href="#copy.28.29">copy</a>(in <a href="en/NsIAbCard">nsIAbCard</a> srcCard)</code>
</td></tr>
<tr>
<td> <code>boolean <a href="#equals.28.29">equals</a>(in <a href="en/NsIAbCard">nsIAbCard</a> card)</code>
</td></tr>
<tr>
<td> <code>AString <a href="#generatePhoneticName.28.29">generatePhoneticName</a>(in boolean aLastNameFirst)</code>
</td></tr>
</tbody></table>
<h2 id="Attributes" name="Attributes">Attributes</h2>
<table class="standard-table"> <tbody><tr>
<td class="header">Attribute
</td><td class="header">Type
</td><td class="header">Description
</td></tr>
<tr>
<td><code>properties</code>
</td><td>{{ Interface("nsISimpleEnumerator") }}
</td><td> <b>Readonly:</b> A list of all the properties that this card has as an enumerator, whose members are all <a href="en/NsIProperty">nsIProperty</a> objects.
</td></tr>
<tr>
<td> <code>firstName</code>
</td><td> <code>AString</code>
</td><td> Shorthand for getProperty and setProperty.
</td></tr>
<tr>
<td> <code>lastName</code>
</td><td> <code>AString</code>
</td><td> Shorthand for getProperty and setProperty.
</td></tr>
<tr>
<td> <code>displayName</code>
</td><td> <code>AString</code>
</td><td> Shorthand for getProperty and setProperty.
</td></tr>
<tr>
<td> <code>primaryEmail</code>
</td><td> <code>AString</code>
</td><td> Shorthand for getProperty and setProperty.
</td></tr>
<tr>
<td> isMailList
</td><td> <code>boolean</code>
</td><td> If <code>isMailList</code> is true then <code>mailListURI</code> will contain the <a href="en/URI">URI</a> of the associated mail list. <div class="warning">This will be removed from the interface at a later date.</div>
</td></tr>
<tr>
<td>mailListURI
</td><td><code>string</code>
</td><td> If <code>isMailList</code> is true then <code>mailListURI</code> will contain the <a href="en/URI">URI</a> of the associated mail list. <div class="warning">This will be removed from the interface at a later date.</div>
</td></tr>
</tbody></table>
<h2 id="Methods" name="Methods">Methods</h2>
<h3 id="getProperty.28.29" name="getProperty.28.29">getProperty()</h3>
<p>Returns a property for the given name.
</p>
<pre class="eval"> nsIVariant getProperty(in AUTF8String name, in nsIVariant defaultValue);
</pre>
<h6 id="Parameters" name="Parameters">Parameters</h6>
<dl><dt><tt>name</tt>
</dt><dd> The case-sensitive name of the property to get.
</dd><dt><tt>defaultValue</tt>
</dt><dd> The value to return if the property does not exist.
</dd></dl>
<h6 id="Return_value" name="Return_value">Return value</h6>
<dl><dd>The value of the attribute asked for.
</dd></dl>
<h6 id="Exceptions_Thrown" name="Exceptions_Thrown">Exceptions Thrown</h6>
<dl><dt><tt>NS_ERROR_NOT_AVAILABLE&lt;tt&gt;
</tt></dt><dd> If the named property does not exist.
</dd><dt>&lt;tt&gt;NS_ERROR_CANNOT_CONVERT_DATA
</dt><dd> If the property cannot be converted to the desired type.
</dd></dl>
<h3 id="getPropertyAsAString.28.29" name="getPropertyAsAString.28.29">getPropertyAsAString()</h3>
<h3 id="getPropertyAsAUTF8String.28.29" name="getPropertyAsAUTF8String.28.29">getPropertyAsAUTF8String()</h3>
<h3 id="getPropertyAsUint32.28.29" name="getPropertyAsUint32.28.29">getPropertyAsUint32()</h3>
<h3 id="getPropertyAsBool.28.29" name="getPropertyAsBool.28.29">getPropertyAsBool()</h3>
<pre class="eval"> [noscript] AString getPropertyAsAString(in string name);
 [noscript] AUTF8String getPropertyAsAUTF8String(in string name);
 [noscript] PRUint32 getPropertyAsUint32(in string name);
 [noscript] boolean getPropertyAsBool(in string name);
</pre>
<p>Returns a property for the given name. These functions convert values in the same manner as the default implementation of <a href="en/NsIVariant">nsIVariant</a>. Of particular note is that boolean variables are converted to integers as in C/C++ (true is a non-zero value), so that <code>false</code> will be converted to a string of <code>0</code> and not <code>false&lt;code&gt;.
</code></p><p>These functions are marked &lt;code&gt;{{ mediawiki.external('noscript') }} since <a href="en/XPCconnect">XPCconnect</a> performs automatic type conversion on <a href="en/NsIVariant">nsIVariant</a> such that they are not needed for scripts, only for C++ callers.
</p>
<h6 id="Parameters_2" name="Parameters_2">Parameters</h6>
<dl><dt><tt>name</tt>
</dt><dd> The case-sensitive name of the property to get.
</dd></dl>
<h6 id="Return_value_2" name="Return_value_2">Return value</h6>
<dl><dd>The value of the attribute asked for.
</dd></dl>
<h6 id="Exceptions_Thrown_2" name="Exceptions_Thrown_2">Exceptions Thrown</h6>
<dl><dt><tt>NS_ERROR_NOT_AVAILABLE&lt;tt&gt;
</tt></dt><dd> If the named property does not exist.
</dd><dt>&lt;tt&gt;NS_ERROR_CANNOT_CONVERT_DATA
</dt><dd> If the property cannot be converted to the desired type.
</dd></dl>
<pre class="eval"> [noscript] AString getPropertyAsAString(in string name);
 [noscript] AUTF8String getPropertyAsAUTF8String(in string name);
 [noscript] PRUint32 getPropertyAsUint32(in string name);
 [noscript] boolean getPropertyAsBool(in string name);
</pre>
<h3 id="setProperty.28.29" name="setProperty.28.29">setProperty()</h3>
<h3 id="setPropertyAsAString.28.29" name="setPropertyAsAString.28.29">setPropertyAsAString()</h3>
<h3 id="setPropertyAsAUTF8String.28.29" name="setPropertyAsAUTF8String.28.29">setPropertyAsAUTF8String()</h3>
<h3 id="setPropertyAsUint32.28.29" name="setPropertyAsUint32.28.29">setPropertyAsUint32()</h3>
<h3 id="setPropertyAsBool.28.29" name="setPropertyAsBool.28.29">setPropertyAsBool()</h3>
<p>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.
</p><p>These functions convert values in the same manner as the default implementation of <a href="en/NsIVariant">nsIVariant</a>.
</p>
<div class="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.</div>
<p>The non-variant functions are marked <code>{{ mediawiki.external('noscript') }}</code> since <a href="en/XPConnect">XPConnect</a> uses magic with <a href="en/NsIVariant">nsIVariant</a> such that the other functions are not needed, although C++ does need them.
</p>
<pre class="eval"> 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);
</pre>
<h6 id="Parameters_3" name="Parameters_3">Parameters</h6>
<dl><dt><tt>name</tt>
</dt><dd> The case-sensitive name of the property to set.
</dd><dt><tt>value</tt>
</dt><dd> The new value of the property.
</dd></dl>
<h3 id="deleteProperty.28.29" name="deleteProperty.28.29">deleteProperty()</h3>
<p>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.
</p>
<pre class="eval"> void deleteProperty(in AUTF8String name);
</pre>
<h6 id="Parameters_4" name="Parameters_4">Parameters</h6>
<dl><dt><tt>name</tt>
</dt><dd> The case-sensitive name of the property to set.
</dd></dl>
<h3 id="translateTo.28.29" name="translateTo.28.29">translateTo()</h3>
<p>Translates a card into a specific format. The following types are supported:
</p>
<ul><li> <code>base64xml</code>
</li><li> <code>xml</code>
</li><li> <code>vcard</code>
</li></ul>
<pre class="eval"> AUTF8String translateTo(in AUTF8String aType);
</pre>
<h6 id="Parameters_5" name="Parameters_5">Parameters</h6>
<dl><dt><tt>aType</tt>
</dt><dd> The type of item to translate the card into.
</dd></dl>
<h6 id="Return_value_3" name="Return_value_3">Return value</h6>
<p>A string containing the translated card.
</p>
<h6 id="Exceptions_Thrown_3" name="Exceptions_Thrown_3">Exceptions Thrown</h6>
<dl><dt><tt>NS_ERROR_ILLEGAL_VALUE</tt>
</dt><dd> Type not recognized.
</dd></dl>
<h3 id="copy.28.29" name="copy.28.29">copy()</h3>
<p>This function will copy all values from one card to another.
</p>
<pre class="eval">void copy(in nsIAbCard srcCard)
</pre>
<h6 id="Parameters_6" name="Parameters_6">Parameters</h6>
<dl><dt><tt>srcCard</tt>
</dt><dd>The source card to copy values from. </dd></dl>
<h3 id="equals.28.29" name="equals.28.29">equals()</h3>
<p>Returns <code>true</code> if this card is equal to the other card.
The default implementation defines equal as this card pointing to the same object as <code>aCard</code>. Another implementation defines it as equality of properties and values.
</p>
<div class="warning">The exact nature of equality is still undefined, and actual results may not match theoretical results. Most notably, the code <tt>a.equals(b) == b.equals(a)</tt> might not return <code>true</code>. In particular, calling equals on cards from different address books may return inaccurate results.</div>
<pre class="eval">boolean equals(in nsIAbCard card)
</pre>
<h6 id="Parameters_7" name="Parameters_7">Parameters</h6>
<dl><dt><tt>card</tt>
</dt><dd>The card you are comparing with.
</dd></dl>
<h6 id="Return_value_4" name="Return_value_4">Return value</h6>
<dl><dd><code>true</code> if the cards are the same.
</dd></dl>
<h3 id="generatePhoneticName.28.29" name="generatePhoneticName.28.29">generatePhoneticName()</h3>
<p>Generate a phonetic name from the card, using the firstName and lastName values.
</p>
<pre class="eval">AString generatePhoneticName(in boolean aLastNameFirst)
</pre>
<h6 id="Parameters_8" name="Parameters_8">Parameters</h6>
<dl><dt><tt>aLastNameFirst</tt>
</dt><dd>Set to <code>true</code> to put the last name before the first. </dd></dl>
<h6 id="Return_value_5" name="Return_value_5">Return value</h6>
<dl><dd>A string containing the generated phonetic name.
</dd></dl>
Revert to this revision