Annotations Class Reference

`#include <annotations.h>`

Inheritance diagram for Annotations:
[legend]

## Public Member Functions

| Annotations (ClientBase *parent)
virtual | ~Annotations ()
void | storeAnnotations (const AnnotationsList &aList)
void | requestAnnotations ()
void | registerAnnotationsHandler (AnnotationsHandler *ah)
void | removeAnnotationsHandler ()
virtual void | handlePrivateXML (const Tag *xml)
virtual void | handlePrivateXMLResult (const std::string &uid, PrivateXMLResult pxResult)
Public Member Functions inherited from PrivateXML
| PrivateXML (ClientBase *parent)
virtual | ~PrivateXML ()
std::string | requestXML (const std::string &tag, const std::string &xmlns, PrivateXMLHandler *pxh)
std::string | storeXML (const Tag *tag, PrivateXMLHandler *pxh)
virtual bool | handleIq (const IQ &iq)
virtual void | handleIqID (const IQ &iq, int context)
Public Member Functions inherited from IqHandler
virtual | ~IqHandler ()
Public Member Functions inherited from PrivateXMLHandler
virtual | ~PrivateXMLHandler ()

## Additional Inherited Members

Public Types inherited from PrivateXMLHandler
enum | PrivateXMLResult { PxmlStoreOk , PxmlStoreError , PxmlRequestError }

## Detailed Description

This is an implementation of XEP-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;
}
gloox::AnnotationsHandler
A virtual interface which can be reimplemented to receive notes with help of the Annotations object.
Definition annotationshandler.h:50
gloox::AnnotationsHandler::handleAnnotations
virtual void handleAnnotations(const AnnotationsList &aList)=0
gloox::Annotations::Annotations
Annotations(ClientBase *parent)
Definition annotations.cpp:22
gloox::AnnotationsList
std::list< AnnotationsListItem > AnnotationsList
Definition annotationshandler.h:40

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 Schröter js@ca.nosp@m.maya.nosp@m..net

Since
  0.3

Definition at line 94 of file annotations.h.

## Constructor & Destructor Documentation

## Annotations()

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

~Annotations | ( |  | ) |

virtual

Virtual destructor.

Definition at line 28 of file annotations.cpp.

## Member Function Documentation

## handlePrivateXML()

void handlePrivateXML | ( | const Tag * | xml | ) |

virtual

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

Parameters

  xml | The private xml, i.e. the first child of the <query> tag. May be 0. You should not delete the object.

Implements PrivateXMLHandler.

Definition at line 53 of file annotations.cpp.

## handlePrivateXMLResult()

void handlePrivateXMLResult | ( | const std::string & | uid,
|  | PrivateXMLResult | pxResult )

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.
  pxResult | The result of the operation.

Since
  0.7

Implements PrivateXMLHandler.

Definition at line 86 of file annotations.cpp.

## registerAnnotationsHandler()

void registerAnnotationsHandler | ( | AnnotationsHandler * | ah | ) |

inline

Use this function to register a AnnotationsHandler.

Parameters

  ah | The AnnotationsHandler which shall receive retrieved notes.

Definition at line 125 of file annotations.h.

## removeAnnotationsHandler()

void removeAnnotationsHandler | ( |  | ) |

inline

Use this function to un-register the AnnotationsHandler.

Definition at line 131 of file annotations.h.

## requestAnnotations()

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 48 of file annotations.cpp.

## storeAnnotations()

void storeAnnotations | ( | const 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.

The documentation for this class was generated from the following files:

- annotations.h
- annotations.cpp