void addObserver ( nsIAnnotationObserver observer )

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

Arguments:

observer

void copyItemAnnotations ( PRInt64 sourceItemId , PRInt64 destItemId , PRBool overwriteDest )

Arguments:

sourceItemId

destItemId

overwriteDest

void copyPageAnnotations ( nsIURI sourceURI , nsIURI destURI , PRBool overwriteDest )

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

Arguments:

sourceURI

destURI

overwriteDest

nsIURI getAnnotationURI ( nsIURI URI , AUTF8String name )

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.

Arguments:

URI

name

nsIVariant getItemAnnotation ( PRInt64 itemId , AUTF8String name )

Arguments:

itemId

name

void getItemAnnotationBinary ( PRInt64 itemId , AUTF8String name , out arrayof PRUint8 data , out PRUint32 dataLen , out AUTF8String mimeType )

Arguments:

itemId

name

data

dataLen

mimeType

double getItemAnnotationDouble ( PRInt64 itemId , AUTF8String name )

Arguments:

itemId

name

void getItemAnnotationInfo ( PRInt64 itemId , AUTF8String name , out PRInt32 flags , out PRUint16 expiration , out AUTF8String mimeType , out PRUint16 type )

Arguments:

itemId

name

flags

expiration

mimeType

type

PRInt32 getItemAnnotationInt32 ( PRInt64 itemId , AUTF8String name )

Arguments:

itemId

name

PRInt64 getItemAnnotationInt64 ( PRInt64 itemId , AUTF8String name )

Arguments:

itemId

name

void getItemAnnotationNames ( PRInt64 itemId , out PRUint32 count , out nsIVariant result )

Arguments:

itemId

count

result

AString getItemAnnotationString ( PRInt64 itemId , AUTF8String name )

Arguments:

itemId

name

PRUint16 getItemAnnotationType ( PRInt64 itemId , AUTF8String name )

Arguments:

itemId

name

void getItemsWithAnnotation ( AUTF8String name , out PRUint32 resultCount , out arrayof PRInt64 results )

Arguments:

name

resultCount

results

nsIVariant getPageAnnotation ( nsIURI URI , AUTF8String name )

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.

Arguments:

URI

name

void getPageAnnotationBinary ( nsIURI URI , AUTF8String name , out arrayof PRUint8 data , out PRUint32 dataLen , out AUTF8String mimeType )

Arguments:

URI

name

data

dataLen

mimeType

double getPageAnnotationDouble ( nsIURI URI , AUTF8String name )

Arguments:

URI

name

void getPageAnnotationInfo ( nsIURI URI , AUTF8String name , out PRInt32 flags , out PRUint16 expiration , out AUTF8String mimeType , out PRUint16 type )

Retrieves info about an existing annotation. mimeType 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'

Arguments:

URI

name

flags

expiration

mimeType

type

PRInt32 getPageAnnotationInt32 ( nsIURI URI , AUTF8String name )

Arguments:

URI

name

PRInt64 getPageAnnotationInt64 ( nsIURI URI , AUTF8String name )

Arguments:

URI

name

void getPageAnnotationNames ( nsIURI URI , out PRUint32 count , out nsIVariant result )

Get the names of all annotations for this URI.

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

Arguments:

URI

count

result

AString getPageAnnotationString ( nsIURI URI , AUTF8String name )

Arguments:

URI

name

PRUint16 getPageAnnotationType ( nsIURI URI , AUTF8String name )

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

Arguments:

URI: the uri on which the annotation is set

name: the annotation name

Returns:

one of the TYPE_* constants above

void getPagesWithAnnotation ( AUTF8String name , out PRUint32 resultCount , out nsIURI results )

Returns a list of all URIs having a given annotation.

Arguments:

name

resultCount

results

PRBool itemHasAnnotation ( PRInt64 itemId , AUTF8String name )

Arguments:

itemId

name

PRBool pageHasAnnotation ( nsIURI URI , AUTF8String name )

Test for annotation existance.

Arguments:

URI

name

void removeItemAnnotation ( PRInt64 itemId , AUTF8String name )

Arguments:

itemId

name

void removeItemAnnotations ( PRInt64 itemId )

Arguments:

itemId

void removeObserver ( nsIAnnotationObserver observer )

Removes an annotaton observer previously registered by addObserver.

Arguments:

observer

void removePageAnnotation ( nsIURI URI , AUTF8String name )

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

Arguments:

URI

name

void removePageAnnotations ( nsIURI URI )

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

Arguments:

URI

void setItemAnnotation ( PRInt64 itemId , AUTF8String name , nsIVariant value , PRInt32 flags , PRUint16 expiration )

Arguments:

itemId

name

value

flags

expiration

void setItemAnnotationBinary ( PRInt64 itemId , AUTF8String name , arrayof PRUint8 data , PRUint32 dataLen , AUTF8String mimeType , PRInt32 flags , PRUint16 expiration )

Arguments:

itemId

name

data

dataLen

mimeType

flags

expiration

void setItemAnnotationDouble ( PRInt64 itemId , AUTF8String name , double value , PRInt32 flags , PRUint16 expiration )

Arguments:

itemId

name

value

flags

expiration

void setItemAnnotationInt32 ( PRInt64 itemId , AUTF8String name , PRInt32 value , PRInt32 flags , PRUint16 expiration )

Arguments:

itemId

name

value

flags

expiration

void setItemAnnotationInt64 ( PRInt64 itemId , AUTF8String name , PRInt64 value , PRInt32 flags , PRUint16 expiration )

Arguments:

itemId

name

value

flags

expiration

void setItemAnnotationString ( PRInt64 itemId , AUTF8String name , AString value , PRInt32 flags , PRUint16 expiration )

Arguments:

itemId

name

value

flags

expiration

void setPageAnnotation ( nsIURI URI , AUTF8String name , nsIVariant value , PRInt32 flags , PRUint16 expiration )

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

Arguments:

URI

name

value

flags

expiration

void setPageAnnotationBinary ( nsIURI URI , AUTF8String name , arrayof PRUint8 data , PRUint32 dataLen , AUTF8String mimeType , PRInt32 flags , PRUint16 expiration )

Arguments:

URI

name

data

dataLen

mimeType

flags

expiration

void setPageAnnotationDouble ( nsIURI URI , AUTF8String name , double value , PRInt32 flags , PRUint16 expiration )

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

Arguments:

URI

name

value

flags

expiration

void setPageAnnotationInt32 ( nsIURI URI , AUTF8String name , PRInt32 value , PRInt32 flags , PRUint16 expiration )

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

Arguments:

URI

name

value

flags

expiration

void setPageAnnotationInt64 ( nsIURI URI , AUTF8String name , PRInt64 value , PRInt32 flags , PRUint16 expiration )

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

Arguments:

URI

name

value

flags

expiration

void setPageAnnotationString ( nsIURI URI , AUTF8String name , AString value , PRInt32 flags , PRUint16 expiration )

Arguments:

URI

name

value

flags

expiration