Annotations Class Reference

This is an implementation of JEP-0145 (Annotations). More...

#include <annotations.h>

Inherits PrivateXML, and PrivateXMLHandler.

Inheritance diagram for Annotations:

Inheritance graph
[legend]
Collaboration diagram for Annotations:

Collaboration graph
[legend]
List of all members.

Public Member Functions

 Annotations (ClientBase *parent)
virtual ~Annotations ()
void storeAnnotations (const AnnotationsHandler::AnnotationsList &aList)
void requestAnnotations ()
void registerAnnotationsHandler (AnnotationsHandler *ah)
void removeAnnotationsHandler ()
virtual void handlePrivateXML (const std::string &tag, Tag *xml)
virtual void handlePrivateXMLResult (const std::string &uid, PrivateXMLResult result)

Detailed Description

This is an implementation of JEP-0145 (Annotations).

You can use this class to store arbitrary notes about a roster item on the server (and to retrieve them later on). To retrieve all stored annotations for the current user's roster you have to create a class which inherits from AnnotationsHandler. This handler receives retrieved notes.

 class MyClass : public AnnotationsHandler
 {
   public:
     // ...
     void myFuncRetrieve();
     void myFuncStore();
     void handleAnnotations( const AnnotationsList &aList );

   private:
     Annotations *m_notes;
     AnnotationsList m_list;
 };

 void MyClass::myFuncRetrieve()
 {
   [...]
   m_notes = new Annotations( m_client );
   m_notes->requestAnnotations();
 }

 void MyClass::handleAnnotations( const AnnotationsList &aList )
 {
   m_list = aList;
 }

To store an additional note you have to fetch the currently stored notes first, add your new note to the list of notes, and transfer them all together back to the server. This protocol does not support storage of 'deltas', that is, when saving notes all previously saved notes are overwritten.

 void MyClass::myFuncStore()
 {
   annotationsListItem item;
   item.jid = "me@example.com";
   item.cdate = "2006-02-04T15:23:21Z";
   item.note = "some guy at example.com";
   m_list.push_back( item );

   item.jid = "abc@def.com";
   item.cdate = "2006-01-24T15:23:21Z";
   item.mdate = "2006-02-04T05:11:46Z";
   item.note = "some other guy";
   m_list.push_back( item );

   m_notes->storeAnnotations( m_list );
 }

Author:
Jakob Schroeter <js@camaya.net>
Since:
0.3

Definition at line 94 of file annotations.h.


Constructor & Destructor Documentation

Annotations ( ClientBase parent  ) 

Constructs a new Annotations object.

Parameters:
parent The ClientBase to use for communication.

Definition at line 22 of file annotations.cpp.

~Annotations (  )  [virtual]

Virtual destructor.

Definition at line 28 of file annotations.cpp.


Member Function Documentation

void storeAnnotations ( const AnnotationsHandler::AnnotationsList aList  ) 

Use this function to store notes (annotations to contacts in a roster) on the server. Make sure you store the whole set of annotations, not a 'delta'.

Parameters:
aList A list of notes to store.

Definition at line 32 of file annotations.cpp.

void requestAnnotations (  ) 

Use this function to initiate retrieval of annotations. Use registerAnnotationsHandler() to register an object which will receive the lists of notes.

Definition at line 52 of file annotations.cpp.

void registerAnnotationsHandler ( AnnotationsHandler ah  ) 

Use this function to register a AnnotationsHandler.

Parameters:
ah The AnnotationsHandler which shall receive retrieved notes.

Definition at line 91 of file annotations.cpp.

void removeAnnotationsHandler (  ) 

Use this function to un-register the AnnotationsHandler.

Definition at line 96 of file annotations.cpp.

void handlePrivateXML ( const std::string &  tag,
Tag xml 
) [virtual]

Reimplement this function to receive the private XML that was requested earlier using PrivateXML::requestXML().

Parameters:
tag The tag of the storage packet.
xml The private xml, i.e. the first child of the <query> tag.

Implements PrivateXMLHandler.

Definition at line 57 of file annotations.cpp.

void handlePrivateXMLResult ( const std::string &  uid,
PrivateXMLResult  result 
) [virtual]

This function is called to notify about the result of a 'store' or 'request' operation (successful requests are announced by means of handlePrivateXML()).

Parameters:
uid The ID of the query.
result The result of the operation.
Since:
0.7

Implements PrivateXMLHandler.

Definition at line 87 of file annotations.cpp.


The documentation for this class was generated from the following files:
Generated on Tue May 1 14:20:21 2007 for gloox by  doxygen 1.5.1