1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
|
/*
Copyright (c) 2005-2016 by Jakob Schröter <js@camaya.net>
This file is part of the gloox library. http://camaya.net/gloox
This software is distributed under a license. The full license
agreement can be found in the file LICENSE in this distribution.
This software may not be copied, modified, sold or distributed
other than expressed in the named license agreement.
This software is distributed without any warranty.
*/
#ifndef ANNOTATIONS_H__
#define ANNOTATIONS_H__
#include "macros.h"
#include "annotationshandler.h"
#include "privatexml.h"
#include "privatexmlhandler.h"
#include <string>
#include <list>
namespace gloox
{
class Tag;
/**
* @brief 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.
*
* @code
* 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;
* }
* @endcode
*
* 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.
*
* @code
* 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 );
* }
* @endcode
*
* @author Jakob Schröter <js@camaya.net>
* @since 0.3
*/
class GLOOX_API Annotations : public PrivateXML, public PrivateXMLHandler
{
public:
/**
* Constructs a new Annotations object.
* @param parent The ClientBase to use for communication.
*/
Annotations( ClientBase* parent );
/**
* Virtual destructor.
*/
virtual ~Annotations();
/**
* 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'.
* @param aList A list of notes to store.
*/
void storeAnnotations( const AnnotationsList& aList );
/**
* Use this function to initiate retrieval of annotations. Use registerAnnotationsHandler()
* to register an object which will receive the lists of notes.
*/
void requestAnnotations();
/**
* Use this function to register a AnnotationsHandler.
* @param ah The AnnotationsHandler which shall receive retrieved notes.
*/
void registerAnnotationsHandler( AnnotationsHandler* ah )
{ m_annotationsHandler = ah; }
/**
* Use this function to un-register the AnnotationsHandler.
*/
void removeAnnotationsHandler()
{ m_annotationsHandler = 0; }
// reimplemented from PrivateXMLHandler
virtual void handlePrivateXML( const Tag* xml );
// reimplemented from PrivateXMLHandler
virtual void handlePrivateXMLResult( const std::string& uid, PrivateXMLResult pxResult );
private:
AnnotationsHandler* m_annotationsHandler;
};
}
#endif // ANNOTATIONS_H__
|
