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)
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)
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)
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)
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)
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)
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)
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)
PRUint16	getItemAnnotationType (in long long aItemId, in AUTF8String aName)
void	getPagesWithAnnotation (in AUTF8String name, out unsigned long resultCount,[retval, array, size_is(resultCount)] out nsIURI results)
void	getItemsWithAnnotation (in AUTF8String name, out unsigned long resultCount,[retval, array, size_is(resultCount)] out long long results)
void	getPageAnnotationNames (in nsIURI aURI, out unsigned long count,[retval, array, size_is(count)] out nsIVariant result)
void	getItemAnnotationNames (in long long aItemId, out unsigned long count,[retval, array, size_is(count)] out nsIVariant result)
boolean	pageHasAnnotation (in nsIURI aURI, in AUTF8String aName)
boolean	itemHasAnnotation (in long long aItemId, in AUTF8String aName)
void	removePageAnnotation (in nsIURI aURI, in AUTF8String aName)
void	removeItemAnnotation (in long long aItemId, in AUTF8String aName)
void	removePageAnnotations (in nsIURI aURI)
void	removeItemAnnotations (in long long aItemId)
void	copyPageAnnotations (in nsIURI aSourceURI, in nsIURI aDestURI, in boolean aOverwriteDest)
void	copyItemAnnotations (in long long aSourceItemId, in long long aDestItemId, in boolean aOverwriteDest)
void	addObserver (in nsIAnnotationObserver aObserver)
void	removeObserver (in nsIAnnotationObserver aObserver)
nsIURI	getAnnotationURI (in nsIURI aURI, in AUTF8String aName)
Public Attributes
const unsigned short	EXPIRE_SESSION = 0
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

---

Detailed Description

Definition at line 64 of file nsIAnnotationService.idl.

---

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

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,
		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,
		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
	)

See also:

getPageAnnotation

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
	)

See also:

getPageAnnotation

long long nsIAnnotationService::getPageAnnotationInt64	(	in nsIURI	aURI,
		in AUTF8String	aName
	)

See also:

getPageAnnotation

void nsIAnnotationService::getPageAnnotationNames	(	in nsIURI	aURI,
		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
	)

See also:

getPageAnnotation

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,
		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 existance.

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

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.

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.

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.

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

---

Member Data Documentation

const unsigned short nsIAnnotationService::EXPIRE_DAYS = 6

Definition at line 105 of file nsIAnnotationService.idl.

const unsigned short nsIAnnotationService::EXPIRE_MONTHS = 3

Definition at line 91 of file nsIAnnotationService.idl.

const unsigned short nsIAnnotationService::EXPIRE_NEVER = 4

Definition at line 97 of file nsIAnnotationService.idl.

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.

Definition at line 76 of file nsIAnnotationService.idl.

const unsigned short nsIAnnotationService::EXPIRE_WEEKS = 2

Definition at line 83 of file nsIAnnotationService.idl.

const unsigned short nsIAnnotationService::EXPIRE_WITH_HISTORY = 5

Definition at line 101 of file nsIAnnotationService.idl.

const unsigned short nsIAnnotationService::TYPE_BINARY = 4

Definition at line 111 of file nsIAnnotationService.idl.

const unsigned short nsIAnnotationService::TYPE_DOUBLE = 2

Definition at line 109 of file nsIAnnotationService.idl.

const unsigned short nsIAnnotationService::TYPE_INT32 = 1

Definition at line 108 of file nsIAnnotationService.idl.

const unsigned short nsIAnnotationService::TYPE_INT64 = 5

Definition at line 112 of file nsIAnnotationService.idl.

const unsigned short nsIAnnotationService::TYPE_STRING = 3

Definition at line 110 of file nsIAnnotationService.idl.

---

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

• /Users/dietrich/moz/trunk/mozilla/toolkit/components/places/public/nsIAnnotationService.idl