Public Member Functions | Public Attributes

nsIAnnotationService Interface Reference

import "nsIAnnotationService.idl";

List of all members.

Public Member Functions

void setPageAnnotation (in nsIURI aURI, in AUTF8String aName, in nsIVariant aValue, in long aFlags, in unsigned short aExpiration)
 Sets an annotation, overwriting any previous annotation with the same URL/name.
void setItemAnnotation (in long long aItemId, in AUTF8String aName, in nsIVariant aValue, in long aFlags, in unsigned short aExpiration)
void setPageAnnotationString (in nsIURI aURI, in AUTF8String aName, in AString aValue, in long aFlags, in unsigned short aExpiration)
void setItemAnnotationString (in long long aItemId, in AUTF8String aName, in AString aValue, in long aFlags, in unsigned short aExpiration)
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 Int32 as input.
void setItemAnnotationInt32 (in long long aItemId, in AUTF8String aName, in long aValue, in long aFlags, in unsigned short aExpiration)
void setPageAnnotationInt64 (in nsIURI aURI, in AUTF8String aName, in long long aValue, in long aFlags, in unsigned short aExpiration)
 Sets an annotation just like setAnnotationString, but takes an Int64 as input.
void setItemAnnotationInt64 (in long long aItemId, in AUTF8String aName, in long long aValue, in long aFlags, in unsigned short aExpiration)
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 a double as input.
void setItemAnnotationDouble (in long long aItemId, in AUTF8String aName, in double aValue, in long aFlags, in unsigned short aExpiration)
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)
 Sets an annotation just like setAnnotationString, but takes binary data as input.
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)
nsIVariant getPageAnnotation (in nsIURI aURI, in AUTF8String aName)
 Retrieves the value of a given annotation.
nsIVariant getItemAnnotation (in long long aItemId, in AUTF8String aName)
AString getPageAnnotationString (in nsIURI aURI, in AUTF8String aName)
AString getItemAnnotationString (in long long aItemId, in AUTF8String aName)
long getPageAnnotationInt32 (in nsIURI aURI, in AUTF8String aName)
long getItemAnnotationInt32 (in long long aItemId, in AUTF8String aName)
long long getPageAnnotationInt64 (in nsIURI aURI, in AUTF8String aName)
long long getItemAnnotationInt64 (in long long aItemId, in AUTF8String aName)
double getPageAnnotationDouble (in nsIURI aURI, in AUTF8String aName)
double getItemAnnotationDouble (in long long aItemId, in AUTF8String aName)
void getPageAnnotationBinary (in nsIURI aURI, in AUTF8String aName,[array, size_is(aDataLen)] out octet aData, out unsigned long aDataLen, out AUTF8String aMimeType)
void getItemAnnotationBinary (in long long aItemId, in AUTF8String aName,[array, size_is(aDataLen)] out octet aData, out unsigned long aDataLen, out AUTF8String aMimeType)
void getPageAnnotationInfo (in nsIURI aURI, in AUTF8String aName, out PRInt32 aFlags, out unsigned short aExpiration, out AUTF8String aMimeType, out unsigned short aType)
 Retrieves info about an existing annotation.
void getItemAnnotationInfo (in long long aItemId, in AUTF8String aName, out long aFlags, out unsigned short aExpiration, out AUTF8String aMimeType, out unsigned short aType)
PRUint16 getPageAnnotationType (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.
PRUint16 getItemAnnotationType (in long long aItemId, in AUTF8String aName)
void getPagesWithAnnotation (in AUTF8String name,[optional] out unsigned long resultCount,[retval, array, size_is(resultCount)] out nsIURI results)
 Returns a list of all URIs having a given annotation.
void getItemsWithAnnotation (in AUTF8String name,[optional] out unsigned long resultCount,[retval, array, size_is(resultCount)] out long long results)
void getPageAnnotationNames (in nsIURI aURI,[optional] out unsigned long count,[retval, array, size_is(count)] out nsIVariant result)
 Get the names of all annotations for this URI.
void getItemAnnotationNames (in long long aItemId,[optional] out unsigned long count,[retval, array, size_is(count)] out nsIVariant result)
boolean pageHasAnnotation (in nsIURI aURI, in AUTF8String aName)
 Test for annotation existence.
boolean itemHasAnnotation (in long long aItemId, in AUTF8String aName)
void removePageAnnotation (in nsIURI aURI, in AUTF8String aName)
 Removes a specific annotation.
void removeItemAnnotation (in long long aItemId, in AUTF8String aName)
void removePageAnnotations (in nsIURI aURI)
 Removes all annotations for the given page/item.
void removeItemAnnotations (in long long aItemId)
void copyPageAnnotations (in nsIURI aSourceURI, in nsIURI aDestURI, in boolean aOverwriteDest)
 Copies all annotations from the source to the destination URI/item.
void copyItemAnnotations (in long long aSourceItemId, in long long aDestItemId, in boolean aOverwriteDest)
void addObserver (in nsIAnnotationObserver aObserver)
 Adds an annotation observer.
void removeObserver (in nsIAnnotationObserver aObserver)
 Removes an annotaton observer previously registered by addObserver.
nsIURI getAnnotationURI (in nsIURI aURI, in AUTF8String aName)
 Returns a URI that can be used to access the given binary annotation.

Public Attributes

const unsigned short EXPIRE_SESSION = 0
 Valid values for aExpiration, which sets the expiration policy for your annotation.
const unsigned short EXPIRE_WEEKS = 2
const unsigned short EXPIRE_MONTHS = 3
const unsigned short EXPIRE_NEVER = 4
const unsigned short EXPIRE_WITH_HISTORY = 5
const unsigned short EXPIRE_DAYS = 6
const unsigned short TYPE_INT32 = 1
const unsigned short TYPE_DOUBLE = 2
const unsigned short TYPE_STRING = 3
const unsigned short TYPE_BINARY = 4
const unsigned short TYPE_INT64 = 5

Member Function Documentation

void nsIAnnotationService::addObserver ( in nsIAnnotationObserver  aObserver  ) 

Adds an annotation observer.

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

void nsIAnnotationService::copyItemAnnotations ( in long long  aSourceItemId,
in long long  aDestItemId,
in boolean  aOverwriteDest 
)
void nsIAnnotationService::copyPageAnnotations ( in nsIURI  aSourceURI,
in nsIURI  aDestURI,
in boolean  aOverwriteDest 
)

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 original annotation will be preferred.

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

nsIURI nsIAnnotationService::getAnnotationURI ( in nsIURI  aURI,
in AUTF8String  aName 
)

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.

nsIVariant nsIAnnotationService::getItemAnnotation ( in long long  aItemId,
in AUTF8String  aName 
)
void nsIAnnotationService::getItemAnnotationBinary ( in long long  aItemId,
in AUTF8String  aName,
[array, size_is(aDataLen)] out octet  aData,
out unsigned long  aDataLen,
out AUTF8String  aMimeType 
)
double nsIAnnotationService::getItemAnnotationDouble ( in long long  aItemId,
in AUTF8String  aName 
)
void nsIAnnotationService::getItemAnnotationInfo ( in long long  aItemId,
in AUTF8String  aName,
out long  aFlags,
out unsigned short  aExpiration,
out AUTF8String  aMimeType,
out unsigned short  aType 
)
long nsIAnnotationService::getItemAnnotationInt32 ( in long long  aItemId,
in AUTF8String  aName 
)
long long nsIAnnotationService::getItemAnnotationInt64 ( in long long  aItemId,
in AUTF8String  aName 
)
void nsIAnnotationService::getItemAnnotationNames ( in long long  aItemId,
[optional] out unsigned long  count,
[retval, array, size_is(count)] out nsIVariant  result 
)
AString nsIAnnotationService::getItemAnnotationString ( in long long  aItemId,
in AUTF8String  aName 
)
PRUint16 nsIAnnotationService::getItemAnnotationType ( in long long  aItemId,
in AUTF8String  aName 
)
void nsIAnnotationService::getItemsWithAnnotation ( in AUTF8String  name,
[optional] out unsigned long  resultCount,
[retval, array, size_is(resultCount)] out long long  results 
)
nsIVariant nsIAnnotationService::getPageAnnotation ( 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.

void nsIAnnotationService::getPageAnnotationBinary ( in nsIURI  aURI,
in AUTF8String  aName,
[array, size_is(aDataLen)] out octet  aData,
out unsigned long  aDataLen,
out AUTF8String  aMimeType 
)
See also:
getPageAnnotation. This also returns the MIME type.
double nsIAnnotationService::getPageAnnotationDouble ( in nsIURI  aURI,
in AUTF8String  aName 
)
void nsIAnnotationService::getPageAnnotationInfo ( in nsIURI  aURI,
in AUTF8String  aName,
out PRInt32  aFlags,
out unsigned short  aExpiration,
out AUTF8String  aMimeType,
out unsigned short  aType 
)

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'

long nsIAnnotationService::getPageAnnotationInt32 ( in nsIURI  aURI,
in AUTF8String  aName 
)
long long nsIAnnotationService::getPageAnnotationInt64 ( in nsIURI  aURI,
in AUTF8String  aName 
)
void nsIAnnotationService::getPageAnnotationNames ( in nsIURI  aURI,
[optional] out unsigned long  count,
[retval, array, size_is(count)] out nsIVariant  result 
)

Get the names of all annotations for this URI.

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

AString nsIAnnotationService::getPageAnnotationString ( in nsIURI  aURI,
in AUTF8String  aName 
)
PRUint16 nsIAnnotationService::getPageAnnotationType ( 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.

Parameters:
aURI the uri on which the annotation is set
aName the annotation name
Returns:
one of the TYPE_* constants above
Exceptions:
if the annotation is not set
void nsIAnnotationService::getPagesWithAnnotation ( in AUTF8String  name,
[optional] out unsigned long  resultCount,
[retval, array, size_is(resultCount)] out nsIURI  results 
)

Returns a list of all URIs having a given annotation.

boolean nsIAnnotationService::itemHasAnnotation ( in long long  aItemId,
in AUTF8String  aName 
)
boolean nsIAnnotationService::pageHasAnnotation ( in nsIURI  aURI,
in AUTF8String  aName 
)

Test for annotation existence.

void nsIAnnotationService::removeItemAnnotation ( in long long  aItemId,
in AUTF8String  aName 
)
void nsIAnnotationService::removeItemAnnotations ( in long long  aItemId  ) 
void nsIAnnotationService::removeObserver ( in nsIAnnotationObserver  aObserver  ) 

Removes an annotaton observer previously registered by addObserver.

void nsIAnnotationService::removePageAnnotation ( in nsIURI  aURI,
in AUTF8String  aName 
)

Removes a specific annotation.

Succeeds even if the annotation is not found.

void nsIAnnotationService::removePageAnnotations ( in nsIURI  aURI  ) 

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 nsIAnnotationService::setItemAnnotation ( in long long  aItemId,
in AUTF8String  aName,
in nsIVariant  aValue,
in long  aFlags,
in unsigned short  aExpiration 
)
void nsIAnnotationService::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 
)
void nsIAnnotationService::setItemAnnotationDouble ( in long long  aItemId,
in AUTF8String  aName,
in double  aValue,
in long  aFlags,
in unsigned short  aExpiration 
)
void nsIAnnotationService::setItemAnnotationInt32 ( in long long  aItemId,
in AUTF8String  aName,
in long  aValue,
in long  aFlags,
in unsigned short  aExpiration 
)
void nsIAnnotationService::setItemAnnotationInt64 ( in long long  aItemId,
in AUTF8String  aName,
in long long  aValue,
in long  aFlags,
in unsigned short  aExpiration 
)
void nsIAnnotationService::setItemAnnotationString ( in long long  aItemId,
in AUTF8String  aName,
in AString  aValue,
in long  aFlags,
in unsigned short  aExpiration 
)
void nsIAnnotationService::setPageAnnotation ( in nsIURI  aURI,
in AUTF8String  aName,
in nsIVariant  aValue,
in long  aFlags,
in unsigned short  aExpiration 
)

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 PAGE ANNOTATIONS WILL GET DELETED WHEN THE PAGE IS REMOVED FROM HISTORY IF THE PAGE IS NOT BOOKMARKED. This means that if you create an annotation on an unvisited URI, it will get deleted when the browser shuts down. Otherwise, URIs 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 or extension wants to keep, you should add a bookmark for the page and use an EXPIRE_NEVER annotation. This will ensure the annotation exists until the item is removed by the user. See EXPIRE_* constants above for further information.

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.

Exceptions:
NS_ERROR_ILLEGAL_VALUE if the page or the bookmark doesn't exist.
void nsIAnnotationService::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 
)

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

You MUST supply a valid MIME type.

Exceptions:
NS_ERROR_ILLEGAL_VALUE if the page or the bookmark doesn't exist.
void nsIAnnotationService::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 a double as input.

Exceptions:
NS_ERROR_ILLEGAL_VALUE if the page or the bookmark doesn't exist.
void nsIAnnotationService::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 Int32 as input.

Exceptions:
NS_ERROR_ILLEGAL_VALUE if the page or the bookmark doesn't exist.
void nsIAnnotationService::setPageAnnotationInt64 ( in nsIURI  aURI,
in AUTF8String  aName,
in long long  aValue,
in long  aFlags,
in unsigned short  aExpiration 
)

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

Exceptions:
NS_ERROR_ILLEGAL_VALUE if the page or the bookmark doesn't exist.
void nsIAnnotationService::setPageAnnotationString ( in nsIURI  aURI,
in AUTF8String  aName,
in AString  aValue,
in long  aFlags,
in unsigned short  aExpiration 
)
Exceptions:
NS_ERROR_ILLEGAL_VALUE if the page or the bookmark doesn't exist.

Member Data Documentation

const unsigned short nsIAnnotationService::EXPIRE_DAYS = 6
const unsigned short nsIAnnotationService::EXPIRE_MONTHS = 3
const unsigned short nsIAnnotationService::EXPIRE_NEVER = 4
const unsigned short nsIAnnotationService::EXPIRE_SESSION = 0

Valid values for aExpiration, which sets the expiration policy for your annotation.

The times for the days, weeks and months policies are measured since the last visit date of the page in question. These will not expire so long as the user keeps visiting the page from time to time.

const unsigned short nsIAnnotationService::EXPIRE_WEEKS = 2
const unsigned short nsIAnnotationService::TYPE_BINARY = 4
const unsigned short nsIAnnotationService::TYPE_DOUBLE = 2
const unsigned short nsIAnnotationService::TYPE_INT32 = 1
const unsigned short nsIAnnotationService::TYPE_INT64 = 5
const unsigned short nsIAnnotationService::TYPE_STRING = 3

The documentation for this interface was generated from the following file: