netwerk/dns/nsIEffectiveTLDService.idlScriptable
This is an interface that examines a hostname and determines the longest portion that should be treated as though it were a top-level domain (TLD). It can also determine the base domain of a URI.
1.0
66
Introduced
Gecko 1.9
Inherits from: nsISupports Last changed in Gecko 1.9 (Firefox 3)

Implemented by: @mozilla.org/network/effective-tld-service;1. To use this service, use:

var eTLDService = Components.classes["@mozilla.org/network/effective-tld-service;1"]
                  .getService(Components.interfaces.nsIEffectiveTLDService);

The name "Effective TLD Service" is a historical one; today, the items this interface manipulates are called Public Suffixes, and the list of them is the Public Suffix List, or PSL. See publicsuffix.org for more information.

The methods below implement the Public Suffix algorithm in full, including the implicit "*" rule. Therefore, if you call getPublicSuffix("a.b.c.nonexistent"), you will get back "nonexistent" - this "TLD" is not in the public suffix list, but the implicit "*" rule means that it is returned. This is the right answer for e.g. cookie setting and domain highlighting, but you should check whether it's the right answer for your application.

It is not recommended to use this interface for determining whether a given string "is a domain name". That question is unanswerable with 100% accuracy using the PSL, because what is a domain name is a property of the DNS, which is different for different people. Is "mail.intranet" actually a domain name? Depends who you ask - for some people it is, others not. Is "pretty.flowers" a domain name, according to getPublicSuffix()? Depends on the age of the copy of the PSL you are working with. The TLD space is currently expanding at a fairly great rate, and the copy of the PSL Firefox has may not be totally up to date (because it's not dynamically updated data).

Method overview

ACString getBaseDomain(in nsIURI aURI, [optional] in PRUint32 aAdditionalParts);
ACString getBaseDomainFromHost(in AUTF8String aHost, [optional] in PRUint32 aAdditionalParts);
ACString getPublicSuffix(in nsIURI aURI);
ACString getPublicSuffixFromHost(in AUTF8String aHost);

Methods

getBaseDomain()

Returns the base domain of a URI; that is, the public suffix with a given number of additional domain name parts.

ACString getBaseDomain(
  in nsIURI aURI,
  [optional] in PRUint32 aAdditionalParts
);
Parameters
aURI
The URI to be analyzed.
aAdditionalParts
The number of domain name parts to be returned in addition to the public suffix.
Return value

An ACString containing the base domain (public suffix plus the requested number of additional parts).

Exceptions thrown
NS_ERROR_INVALID_ARG
This exception is thrown if the hostname in aURI is empty.
NS_ERROR_INSUFFICIENT_DOMAIN_LEVELS
This exception is thrown if there were insufficient subdomain levels in the hostname to satisfy the requested aAdditionalParts value.
NS_ERROR_HOST_IS_IP_ADDRESS
This exception is thrown if aURI is a numeric IPv4 or IPv6 address.
NS_ERROR_UNEXPECTED
Or other error returned by nsIIDNService.normalize() when the hostname contains characters disallowed in URIs.

getBaseDomainFromHost()

Returns the base domain of a host string. Otherwise identical to getBaseDomain().

Note: It is strongly recommended that you use getBaseDomain() if a suitable nsIURI is available. Only use this method if this is not the case. 

ACString getBaseDomainFromHost(
  in AUTF8String aHost,
  in PRUint32 aAdditionalParts Optional
);
Parameters
aHost
The host string to be analyzed.
aAdditionalParts Optional
The number of domain name parts to be returned in addition to the public suffix.
Return value

An ACString containing the base domain (public suffix plus the requested number of additional parts).

Exceptions thrown
NS_ERROR_INVALID_ARG
This exception is thrown if aHost is empty.
NS_ERROR_UNEXPECTED
This exception originates in the Normalize() method in nsIIDNService and is thrown when aHost contains characters disallowed in URIs.
NS_ERROR_INSUFFICIENT_DOMAIN_LEVELS
This exception is thrown if there were insufficient subdomain levels in the hostname to satisfy the requested aAdditionalParts value.
NS_ERROR_HOST_IS_IP_ADDRESS
This exception is thrown if aHost is a numeric IPv4 or IPv6 address.
Remarks

Note: Prior to Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1), this method worked if you passed host strings starting with a period ("."). That is no longer the case, since these are not valid host names. You should strip leading periods off host names before passing them to this method.

getPublicSuffix()

Returns the public suffix of a URI. A public suffix is the highest-level domain under which individual domains may be registered; it may therefore contain one or more dots. For example, the public suffix for www.bbc.co.uk is co.uk. Likewise, the public suffix for developer.mozilla.org is org.

ACString getPublicSuffix(
  in nsIURI aURI
);
Parameters
aURI
The URI to be analyzed.
Return value

An ACString containing the public suffix.

Exceptions thrown
NS_ERROR_INVALID_ARG
This exception is thrown if the hostname in aURI is empty.
NS_ERROR_HOST_IS_IP_ADDRESS
This exception is thrown if aURI is a numeric IPv4 or IPv6 address.
NS_ERROR_UNEXPECTED
Or other error returned by nsIIDNService.normalize() when the hostname contains characters disallowed in URIs.

getPublicSuffixFromHost()

Returns the public suffix of a host string. Otherwise identical to getPublicSuffix().

Note: It is strongly recommended to use getBaseDomain() if a suitable nsIURI is available. Only use this method if this is not the case.

ACString getPublicSuffixFromHost(
  in AUTF8String aHost
);
Parameters
aHost
The host string to be analyzed.
Return value

An ACString containing the public suffix.

Exceptions thrown
NS_ERROR_INVALID_ARG
This exception is thrown if aHost is empty.
NS_ERROR_UNEXPECTED
This exception originates in the Normalize() method in nsIIDNService and is thrown when aHost contains characters disallowed in URIs.
NS_ERROR_HOST_IS_IP_ADDRESS
This exception is thrown if aHost is a numeric IPv4 or IPv6 address.

Remarks

All returned strings are encoded in ASCII/ACE and normalized according to RFC 3454.