nsIEffectiveTLDService

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

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().

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

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().

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.