nsIAnnotationService

Implemented by: "@mozilla.org/browser/annotation-service;1". To use this service, use:

var annotationService = Components.classes["@mozilla.org/browser/annotation-service;1"]
                        .getService(Components.interfaces.nsIAnnotationService);

Method overview

Constants

Methods

setPageAnnotation()

This method sets an annotation for given URI, 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 "/".

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() or 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
);

Parameters

aURI

The URI on which the annotation is to be set.

aName

The annotation name.

aValue

The annotation value.

aFlags

Should be "0" for now, some flags will be defined in the future.

aExpiration

One of the EXPIRE_* constant value defined above.

setItemAnnotation()

This method sets an annotation for given item, 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 "/".

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() or setPageAnnotationBinary(). For other types, only C++ consumers may use the type-specific methods.

void setItemAnnotation(
  in long long aItemId, 
  in AUTF8String aName,
  in nsIVariant aValue, 
  in long aFlags,
  in unsigned short aExpiration
);

Parameters

aItemID

The item on which the annotation is to be set.

aName

The annotation name.

aValue

The annotation value.

aFlags

Should be "0" for now, some flags will be defined in the future.

aExpiration

One of the EXPIRE_* constant value defined above.

setPageAnnotationString()

This method sets an annotation for given URI by taking a String as input value, 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 "/".

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() or setPageAnnotationBinary(). For other types, only C++ consumers may use the type-specific methods.

void setPageAnnotationString(
  in nsIURI aURI, 
  in AUTF8String aName,
  in AString aValue, 
  in long aFlags,
  in unsigned short aExpiration
);

Parameters

aURI

The URI on which the annotation is to be set.

aName

The annotation name.

aValue

The annotation value.

aFlags

Should be "0" for now, some flags will be defined in the future.

aExpiration

One of the EXPIRE_* constant value defined above.

setItemAnnotationString()

This method sets an annotation for given item by taking a String as input value, 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 "/".

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(). For other types, only C++ consumers may use the type-specific methods.

void setPageAnnotation(
  in long long aItemId, 
  in AUTF8String aName,
  in AString aValue, 
  in long aFlags,
  in unsigned short aExpiration
);

Parameters

aItemID

The item on which the annotation is to be set.

aName

The annotation name.

aValue

The annotation value.

aFlags

Should be "0" for now, some flags will be defined in the future.

aExpiration

One of the EXPIRE_* constant value defined above.

setPageAnnotationInt32()

This method sets an annotation for given URI, just like setPageAnnotationString(), but takes an Int32 as an input.

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

Parameters

aURI

The URI on which the annotation is to be set.

aName

The annotation name.

aValue

The annotation value.

aFlags

Should be "0" for now, some flags will be defined in the future.

aExpiration

One of the EXPIRE_* constant value defined above.

setItemAnnotationInt32()

This method sets an annotation for given item, just like setItemAnnotationString(), but takes an Int32 as an input.

void setItemAnnotationInt32(
  in long long aItemId, 
  in AUTF8String aName,
  in long aValue, 
  in long aFlags,
  in unsigned short aExpiration
);

Parameters

aItemId

The item on which the annotation is to be set.

aName

The annotation name.

aValue

The annotation value.

aFlags

Should be "0" for now, some flags will be defined in the future.

aExpiration

One of the EXPIRE_* constant value defined above.

setPageAnnotationInt64()

This method sets an annotation for given URI, just like setPageAnnotationString(), but takes an Int64 as an input.

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

Parameters

aURI

The URI on which the annotation is to be set.

aName

The annotation name.

aValue

The annotation value.

aFlags

Should be "0" for now, some flags will be defined in the future.

aExpiration

One of the EXPIRE_* constant value defined above.

setItemAnnotationInt64()

This method sets an annotation for given item, just like setItemAnnotationString(), but takes an Int64 as an input.

void setItemAnnotationInt64(
  in long long aItemId, 
  in AUTF8String aName,
  in long long aValue, 
  in long aFlags,
  in unsigned short aExpiration
);

Parameters

aItemId

The item on which the annotation is to be set.

aName

The annotation name.

aValue

The annotation value.

aFlags

Should be "0" for now, some flags will be defined in the future.

aExpiration

One of the EXPIRE_* constant value defined above.

setPageAnnotationDouble()

This method sets an annotation for given URI, just like setPageAnnotationString(), but takes an Double as an input.

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

Parameters

aURI

The URI on which the annotation is to be set.

aName

The annotation name.

aValue

The annotation value.

aFlags

Should be "0" for now, some flags will be defined in the future.

aExpiration

One of the EXPIRE_* constant value defined above.

setItemAnnotationDouble()

This method sets an annotation for given item, just like setItemAnnotationString(), but takes an Double as an input.

void setItemAnnotationDouble(
  in long long aItemId, 
  in AUTF8String aName,
  in double aValue, 
  in long aFlags,
  in unsigned short aExpiration
);

Parameters

aItemId

The item on which the annotation is to be set.

aName

The annotation name.

aValue

The annotation value.

aFlags

Should be "0" for now, some flags will be defined in the future.

aExpiration

One of the EXPIRE_* constant value defined above.

setPageAnnotationBinary()

This method sets an annotation for given URI, just like setPageAnnotationString(), but takes Binary data as an input. You MUST supply a valid MIME type.

void setPageAnnotationBinary(
  in nsIURI aURI, 
  in AUTF8String aName,
  [const,array,size_is(aDataLen)] in octet aData, 
  in unsigned long aDataLen,
  in AUTF8String aMimeType,
  in long aFlags,
  in unsigned short aExpiration
);

Parameters

aURI

The URI on which the annotation is to be set.

aName

The annotation name.

aData

Binary contents of the page to save.

aDataLen

Length of binary data.

aMimeType

MIME type of the data to store. MUST be supplied.

aFlags

Should be "0" for now, some flags will be defined in the future.

aExpiration

One of the EXPIRE_* constant value defined above.

setItemAnnotationBinary()

This method sets an annotation for given item, just like setItemAnnotationString(), but takes Binary data as an input. You MUST supply a valid MIME type.

void setItemAnnotationBinary(
  in long long aItemId, 
  in AUTF8String aName,
  [const,array,size_is(aDataLen)] in octet aData, 
  in unsigned long aDataLen,
  in AUTF8String aMimeType,
  in long aFlags,
  in unsigned short aExpiration
);

Parameters

aItemId

The item on which the annotation is to be set.

aName

The annotation name.

aData

Binary contents of the item to save.

aDataLen

Length of binary data.

aMimeType

MIME type of the data to store. MUST be supplied.

aFlags

Should be "0" for now, some flags will be defined in the future.

aExpiration

One of the EXPIRE_* constant value defined above.

getPageAnnotation()

This method retrieves the value of a given URI annotation. Throws an error if the annotation does not exist. Throws for binary annotations, for which getPageAnnotationBinary() or 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
);

Parameters

aURI

The URI on which the annotation is set.

aName

The annotation name.

Return value

Returns a page annotation.

getItemAnnotation()

This method retrieves the value of a given item annotation. Throws an error if the annotation does not exist. Throws for binary annotations, for which getPageAnnotationBinary() or 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 getItemAnnotation(
  in long long aItemId, 
  in AUTF8String aName
);

Parameters

aItemId

The item on which the annotation is set.

aName

The annotation name.

Return value

Returns an item annotation.

getPageAnnotationString()

This method retrieves the value of a given URI annotation in String format. Throws an error if the annotation does not exist. Throws for binary annotations, for which getPageAnnotationBinary() or 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.

AString getPageAnnotationString(
  in nsIURI aURI, 
  in AUTF8String aName
);

Parameters

aURI

The URI on which the annotation is set.

aName

The annotation name.

Return value

Returns a String value page annotation.

getItemAnnotationString()

This method retrieves the value of a given item annotation in String format. Throws an error if the annotation does not exist. Throws for binary annotations, for which getPageAnnotationBinary() or 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.

AString getItemAnnotationString(
  in long long aItemId, 
  in AUTF8String aName
);

Parameters

aItemId

The item on which the annotation is set.

aName

The annotation name.

Return value

Returns a String value item annotation.

getPageAnnotationInt32()

This method retrieves the value of a given URI annotation in a Int32 format. Throws an error if the annotation does not exist. Throws for binary annotations, for which getPageAnnotationBinary() or 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.

long getPageAnnotationInt32(
  in nsIURI aURI, 
  in AUTF8String aName
);

Parameters

aURI

The URI on which the annotation is set.

aName

The annotation name.

Return value

Returns an Int32 value page annotation.

getItemAnnotationInt32()

This method retrieves the value of a given item annotation in a Int32 format. Throws an error if the annotation does not exist. Throws for binary annotations, for which getPageAnnotationBinary() or 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.

long getItemAnnotationInt32(
  in long long aItemId, 
  in AUTF8String aName
);

Parameters

aItemId

The item on which the annotation is set.

aName

The annotation name.

Return value

Returns an Int32 value item annotation.

getPageAnnotationInt64()

This method retrieves the value of a given URI annotation in a Int64 format. Throws an error if the annotation does not exist. Throws for binary annotations, for which getPageAnnotationBinary() or 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.

long long getPageAnnotationInt64(
  in nsIURI aURI, 
  in AUTF8String aName
);

Parameters

aURI

The URI on which the annotation is set.

aName

The annotation name.

Return value

Returns an Int64 value page annotation.

getItemAnnotationInt64()

This method retrieves the value of a given item annotation in a Int64 format. Throws an error if the annotation does not exist. Throws for binary annotations, for which getPageAnnotationBinary() or 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.

long long getItemAnnotationInt64(
  in long long aItemId, 
  in AUTF8String aName
);

Parameters

aItemId

The item on which the annotation is set.

aName

The annotation name.

Return value

Returns an Int64 value item annotation.

getPageAnnotationDouble()

This method retrieves the value of a given URI annotation in Double format. Throws an error if the annotation does not exist. Throws for binary annotations, for which getPageAnnotationBinary() or 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.

double getPageAnnotationDouble(
  in nsIURI aURI, 
  in AUTF8String aName
);

Parameters

aURI

The URI on which the annotation is set.

aName

The annotation name.

Return value

Returns a Double value page annotation.

getItemAnnotationDouble()

This method retrieves the value of a given item annotation in Double format. Throws an error if the annotation does not exist. Throws for binary annotations, for which getPageAnnotationBinary() or 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.

double getItemAnnotationDouble(
  in long long aItemId, 
  in AUTF8String aName
);

Parameters

aItemId

The item on which the annotation is set.

aName

The annotation name.

Return value

Returns a Double value item annotation.

getPageAnnotationBinary()

This method retrieves the value of a given URI annotation in a Binary format. Throws an error if the annotation does not exist. Throws for binary annotations, for which getPageAnnotationBinary() or 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. 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
);

Parameters

aURI

The URI on which the annotation is set.

aName

The annotation name.

aData

Binary contents of the page to retrieve.

aDataLen

Length of binary data.

aMimeType

MIME type of the data to be retrieved.

Return value

Returns a Binary value and a MIME type page annotation.

getItemAnnotationBinary()

This method retrieves the value of a given item annotation in a Binary format. Throws an error if the annotation does not exist. Throws for binary annotations, for which getPageAnnotationBinary() or 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. This also returns the MIME type.

void getItemAnnotationBinary(
  in long long aItemId, 
  in AUTF8String aName,
  [array,size_is(aDataLen)] out octet aData,
  out unsigned long aDataLen,
  out AUTF8String aMimeType
);

Parameters

aItemId

The item on which the annotation is set.

aName

The annotation name.

aData

Binary contents of the item to retrieve.

aDataLen

Length of binary data.

aMimeType

MIME type of the data to be retrieved.

Return value

Returns a Binary value and a MIME type item annotation.

getPageAnnotationInfo()

This method retrieves info about an existing annotation for the given URI.

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

Parameters

aURI

The URI on which the annotation is set.

aName

The annotation name.

aFlags

Should be "0" for now, some flags will be defined in the future.

aExpiration

One of the EXPIRE_* constant value defined above.

aMimeType

MIME type of the data to be retrieved. Default to "0" if value was not binary data.

aType

One of TYPE_* constansts defined above.

getItemAnnotationInfo()

This method retrieves info about an existing annotation for the given item.

void getItemAnnotationInfo(
  in long long aItemId,
  in AUTF8String aName,
  out long aFlags,
  out unsigned short aExpiration,
  out AUTF8String aMimeType,
  out unsigned short aType
);

Parameters

aItemId

The item on which the annotation is set.

aName

The annotation name.

aFlags

Should be "0" for now, some flags will be defined in the future.

aExpiration

One of the EXPIRE_* constant value defined above.

aMimeType

MIME type of the data to be retrieved. Default to "0" if value was not binary data.

aType

One of TYPE_* constansts defined above.

getPageAnnotationType()

This method retrieves the type of an existing annotation. Use getAnnotationInfo() method, if you need this along with the mime-type etc. It throwns an exception if the annotation is not set.

PRUint16 getPageAnnotationType(
  in nsIURI aURI, 
  in AUTF8String aName
);

Parameters

aURI

The URI on which the annotation is set.

aName

The annotation name.

Return value

Returns one of the TYPE_* constants defined above.

getItemAnnotationType()

This method retrieves the type of an existing annotation. Use getAnnotationInfo() method, if you need this along with the mime-type etc. It throwns an exception if the annotation is not set.

PRUint16 getPageAnnotationType(
  in long long aItemId, 
  in AUTF8String aName
);

Parameters

aURI

The item on which the annotation is set.

aName

The annotation name.

Return value

Returns one of the TYPE_* constants defined above.

getPagesWithAnnotation()

This method returns a list of all URIs having a given annotation.

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

Parameters

name

The annotation name.

resultCount Optional

Count of URIs.

results

Returns the list of all URIs.

getItemsWithAnnotation()

This method returns a list of all items having a given annotation.

void getItemsWithAnnotation(
  in AUTF8String name,
  [optional] out unsigned long resultCount,
  [retval, array, size_is(resultCount)] out long long results
);

Parameters

name

The annotation name.

resultCount Optional

Count of items.

results

Returns the list of all items.

getPageAnnotationNames()

This method retrieves the names of all annotations for the given URI.

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

Parameters

aURI

The URI on which the annotation is set.

count Optional

Count of annotation names available.

result

Returns the name of all annotations.

getItemAnnotationNames()

This method retrieves the names of all annotations for the given item.

void getItemAnnotationNames(
  in long long aItemId, 
  [optional] out unsigned long count,
  [retval, array, size_is(count)] out nsIVariant result
);

Parameters

aItemId

The item on which the annotation is set.

count Optional

Count of annotations name available.

result

Returns the name of all annotations.

pageHasAnnotation()

This method tests for annotation existance for given URI.

boolean pageHasAnnotation(
  in nsIURI aURI, 
  in AUTF8String aName
);

Parameters

aURI

The URI on which the annotation is set.

aName

The annotation name.

Return value

Returns true, if an annotation exists for given URI, otherwise returns false.

itemHasAnnotation()

This method tests for annotation existance for given item.

boolean itemHasAnnotation(
  in long long aItemId, 
  in AUTF8String aName
);

Parameters

aItemId

The item on which the annotation is set.

aName

The annotation name.

Return value

Returns true, if an annotation exists for given item, otherwise returns false.

removePageAnnotation()

This method removes a specific annotation for given URI. Succeeds even if the annotation is not found.

void removePageAnnotation(
  in nsIURI aURI, 
  in AUTF8String aName
);

Parameters

aURI

The URI on which the annotation is set.

aName

The annotation name.

removeItemAnnotation()

This method removes a specific annotation for given item. Succeeds even if the annotation is not found.

void removeItemAnnotation(
  in long long aItemId, 
  in AUTF8String aName
);

Parameters

aItemId

The item on which the annotation is set.

aName

The annotation name.

removePageAnnotations()

This method removes all annotations for the given URI. We may want some other similar functions to get annotations with given flags (once we have flags defined).

void removePageAnnotations(
  in nsIURI aURI
);

Parameters

aURI

The URI on which the annotation is set.

removeItemAnnotations()

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

void removeItemAnnotations(
  in long long aItemId
);

Parameters

aItemId

The item on which the annotation is set.

copyPageAnnotations()

This method copies all annotations from the source to the destination URI. 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
);

Parameters

aSourceItemId

Source item.

aDestItemId

Destination item.

aOverwriteDest

If you want to overwrite existing annotation, set this parameter to true, or else set it to false.

copyItemAnnotations()

This method copies all annotations from the source to the destination 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 copyItemAnnotations(
  in long long aSourceItemId, 
  in long long aDestItemId,
  in boolean aOverwriteDest
);

Parameters

aSourceItemId

Source item.

aDestItemId

Destination item.

aOverwriteDest

If you want to overwrite existing annotation, set this parameter to true or else false.

addObserver()

This method adds an annotation observer. The annotation service will keep an owning reference to the observer object.

void addObserver(
  in nsIAnnotationObserver aObserver
);

Parameters

aObserver

Annotation observer.

removeObserver()

This method removes an annotaton observer previously registered by addObserver() method.

void removeObserver(
  in nsIAnnotationObserver aObserver
);

Parameters

aObserver

Annotation observer.

getAnnotationURI()

This method returns a URI that can be used to access the given binary annotation. This method 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 setPageAnnotationBinary() or setItemAnnotationBinary() methods. No non-URI valid chars in name, especially colon, which will mess up parsing.

nsIURI getAnnotationURI(
  in nsIURI aURI, 
  in AUTF8String aName
);

Parameters

aURI

The URI on which the annotation is set.

aName

The annotation name.

Return value

Returns a URI that can be used to access the given binary annotation.

See also

• Places
• Using the Places annotation service
• Using the Places favicon service
• nsIAnnotationObserver