nsIAnnotationService Interface

 Adds an annotation observer. The annotation service will keep an owning
 reference to the observer object.

void addObserver(in nsIAnnotationObserver aObserver)

 Copies all annotations from the source to the destination URI/item. If
 the destination already has an annotation with the same name as one on
 the source, it will be overwritten if aOverwriteDest is set. Otherwise,
 the destination URIs will be preferred.

 All the source annotations will stay as-is. If you don't want them
 any more, use removePageAnnotations on that URI.

void copyPageAnnotations(in nsIURI aSourceURI, in nsIURI aDestURI, in boolean aOverwriteDest)

 Returns a URI that can be used to access the given binary annotation.
 This function does NOT check that the annotation exists. Also, note that
 you can only load URIs for annotations that have have a valid MIME type
 set by setAnnotationBinary. No non-URI valid chars in name, especially
 colon, which will mess up parsing.

nsIURI getAnnotationURI(in nsIURI aURI, in AUTF8String aName)

 Retrieves the value of a given annotation. Throws an error if the
 annotation does not exist. Throws for binary annotations, for which
 getPageAnnotationBinary/getItemAnnotationBinary should be used. C++
 consumers may use the type-specific methods.

 The type-specific methods throw if the given annotation is set in
 a different type.

nsIVariant getPageAnnotation(in nsIURI aURI, in AUTF8String aName)

 @see getPageAnnotation. This also returns the
 MIME type.

void getPageAnnotationBinary(in nsIURI aURI, in AUTF8String aName, [array, size_is(aDataLen)] out octet aData, out unsigned long aDataLen, out AUTF8String aMimeType)

 @see getPageAnnotation

[noscript] double getPageAnnotationDouble(in nsIURI aURI, in AUTF8String aName)

 Retrieves info about an existing annotation. aMimeType will be empty
 if the value was not binary data.

 aType will be one of TYPE_* constansts above

 example JS:
   var flags = {}, exp = {}, mimeType = {};
   annotator.getAnnotationInfo(myURI, "foo", flags, exp, mimeType);
   // now you can use 'exp.value' and 'flags.value'

void getPageAnnotationInfo(in nsIURI aURI, in AUTF8String aName, out PRInt32 aFlags, out unsigned short aExpiration, out AUTF8String aMimeType, out unsigned short aType)

 @see getPageAnnotation

[noscript] long getPageAnnotationInt32(in nsIURI aURI, in AUTF8String aName)

 @see getPageAnnotation

[noscript] long long getPageAnnotationInt64(in nsIURI aURI, in AUTF8String aName)

 Get the names of all annotations for this URI.

 example JS:
   var annotations = annotator.getPageAnnotations(myURI, {});

void getPageAnnotationNames(in nsIURI aURI, out unsigned long count, [array, retval, size_is(count)] out nsIVariant result)

 @see getPageAnnotation

[noscript] AString getPageAnnotationString(in nsIURI aURI, in AUTF8String aName)

 Retrieves the type of an existing annotation
 Use getAnnotationInfo if you need this along with the mime-type etc.

 @param aURI
        the uri on which the annotation is set
 @param aName
        the annotation name
 @return one of the TYPE_* constants above
 @throws if the annotation is not set

PRUint16 getPageAnnotationType(in nsIURI aURI, in AUTF8String aName)

 Returns a list of all URIs having a given annotation.

void getPagesWithAnnotation(in AUTF8String name, out unsigned long resultCount, [array, retval, size_is(resultCount)] out nsIURI results)

 Test for annotation existance.

boolean pageHasAnnotation(in nsIURI aURI, in AUTF8String aName)

 Removes an annotaton observer previously registered by addObserver.

void removeObserver(in nsIAnnotationObserver aObserver)

 Removes a specific annotation. Succeeds even if the annotation is
 not found.

void removePageAnnotation(in nsIURI aURI, in AUTF8String aName)

 Removes all annotations for the given page/item.
 We may want some other similar functions to get annotations with given
 flags (once we have flags defined).

void removePageAnnotations(in nsIURI aURI)

 Sets an annotation, overwriting any previous annotation with the same
 URL/name. IT IS YOUR JOB TO NAMESPACE YOUR ANNOTATION NAMES.
 Use the form "namespace/value", so your name would be like
 "bills_extension/page_state" or "history/thumbnail".

 Do not use characters that are not valid in URLs such as spaces, ":",
 commas, or most other symbols. You should stick to ASCII letters and
 numbers plus "_", "-", and "/".

 aExpiration is one of EXPIRE_* above. aFlags should be 0 for now, some
 flags will be defined in the future.

 NOTE: ALL ANNOTATIONS WILL GET DELETED WHEN THE PAGE IS REMOVED FROM HISTORY,
 UNLESS YOU USE THE EXPIRE_NEVER FLAG. This means that if you create an
 annotation on a random unvisited URI, it will get deleted when the
 browser shuts down. Otherwise, things can exist in history as
 annotations but the user has no way of knowing it, potentially violating
 their privacy expectations about actions such as "Clear history." If
 there is an important annotation that the user wants to keep, you should
 make sure that you use EXPIRE_NEVER. This will ensure the item is never
 completely deleted from the Places database.

 The annotation "favicon" is special. Favicons are stored in the favicon
 service, but are special cased in the protocol handler so they look like
 annotations. Do not set favicons using this service, it will not work.

 Binary annotations should be set using
 setItemAnnotationBinary/setPageAnnotationBinary. For other types, only
 C++ consumers may use the type-specific methods.

void setPageAnnotation(in nsIURI aURI, in AUTF8String aName, in nsIVariant aValue, in long aFlags, in unsigned short aExpiration)

 Sets an annotation just like setAnnotationString, but takes a double as
 input.

[noscript] void setPageAnnotationDouble(in nsIURI aURI, in AUTF8String aName, in double aValue, in long aFlags, in unsigned short aExpiration)

 Sets an annotation just like setAnnotationString, but takes an Int32 as
 input.

[noscript] void setPageAnnotationInt32(in nsIURI aURI, in AUTF8String aName, in long aValue, in long aFlags, in unsigned short aExpiration)

 Sets an annotation just like setAnnotationString, but takes an Int64 as
 input.

[noscript] void setPageAnnotationInt64(in nsIURI aURI, in AUTF8String aName, in long long aValue, in long aFlags, in unsigned short aExpiration)